Introduction

The purpose of this post is to help you create a report website for a team or individual project. Sharing your work with the class and the broader community is important, as you should generate a persistent portfolio of class work to demonstrate your abilities when you apply for a job or academic career.

We will be using GitHub to host and share websites this year because:

• Hosting websites on GitHub Pages is free.
• Git is iterative. As your project evolves, team members and instructors can track how it changes over time.
• Editing content is simple using standard Markdown files either in a browser or through Git desktop clients.

What is a MkDocs GitHub Page?

This tutorial uses MkDocs, a static site generator that automatically converts simple Markdown files (.md) into a clean, searchable, responsive documentation site.

When you push updates to your GitHub repository, an automated tool called GitHub Actions runs in the background. It executes MkDocs, compiles your Markdown content into HTML, and publishes the finished website to GitHub Pages on a hidden branch named gh-pages. The GitHub action mkdocs-build converts your markdown into static HTML, CSS, and JavaScript files inside the ./site folder.

External Resources

• What is Git? (Microsoft Learn)
• Git Wikipedia Page
• Pro Git Book - Getting Started

Procedure

Step 1: Sign in to GitHub

Go to GitHub.com. If you don’t have an account, create one under the free plan, verify your email, and sign in.

Step 2: Select a Template Repository

Navigate to the appropriate template repository for your course:

• RAS 304 Templates

  • 304 Individual Datasheet Template
  • 304 Team Report Template

• RAS 314 Templates

  • 314 Individual Datasheet Template
  • 314 Team Report Template

Step 3: Create Repository from Template

1. Click the green “Use this template” button in the upper-right corner and select “Create a new repository”.
2. Turn On the toggle for “Include all branches”.
3. Name your repository following the standard class format:

<your_ASURITE_id>_<RAS3x4>_<semester><YY>

Naming Examples:

• For ASURITE User ID vs323 in Fall 2026 taking RAS 304:

  • Repo Name: vs323_RAS304_F26

• For ASURITE User ID cactus213 in Spring 2028 taking RAS 314:

  • Repo Name: cactus213_RAS314_S28

4. Leave the Choose Visibility as Public, and click on the Create repository button.

Step 4: Enable Workflow Write Permissions

New repositories default to read-only permissions for automated workflows, which will cause initial builds to fail.

1. In your new repository, go to the Settings tab.
2. Thing the Settings pgae, navigate to Actions $\rightarrow$ General.
3. Scroll down to Workflow permissions.
4. Select Read and write permissions.
5. Click Save.

Step 5: Trigger Build & Set Up GitHub Pages

1. Go to the Actions tab in your repository.

   This is on the top navigation bar, not within the Settings page.

2. Click on the mkdocs-build build (in the left pane).
   1. If it is running or waiting, select the workflow (probably named Initial Commit). Click on the Cancel Workflow button. Then, click on the Re-run jobs button, and choose Re-run all jobs.
   2. If it has a red cross ($\times$), select the workflow (probably named Initial Commit). Click on the Re-run jobs button, and choose Re-run all jobs.
3. Wait 1–3 minutes until you see a green checkmark ($\checkmark$).
4. Navigate to your live site URL:

https://<your_github_username>.github.io/<repository_name>/

Naming Examples:

• For ASURITE User ID vs323 in Fall 2026 taking RAS 304 with GitHub username hypnotoadasu:

  • Repo Name: vs323_RAS304_F26
  • Live Link: https://hypnotoadasu.github.io/vs323_RAS304_F26/

• For ASURITE User ID cactus213 in Spring 2028 taking RAS 314 with GitHub username leela-asu:

  • Repo Name: cactus213_RAS314_S28
  • Live Link: https://leela-asu.github.io/cactus213_RAS314_S28/

5. Congratulations! You have deployed your website. Everytime you push changes to your GitHub repository, the mkdocs-build will run and reflect the new changes.

Help! My Site is Not Building

If your build fails or shows a red cross (❌) in the Actions tab:

1. Fix Permission Denied (403 Exit Code 128):

• Go to Settings → Actions → General.
• Under Workflow permissions, select Read and write permissions and click Save.

2. Re-trigger the Build Pipeline:

• Go to Actions → mkdocs-build → click Run workflow (or click Re-run all jobs on a failed run).
• Alternatively, make a minor edit to docs/index.md and commit it directly on GitHub.

3. Configure Pages Deployment Source:

• Go to Settings → Pages.
• Under Build and deployment → Source, select Deploy from a branch.
• Set Branch to gh-pages and Folder to / (root), then click Save.

Note: The gh-pages branch will only appear in the dropdown menu after the first GitHub Action workflow completes successfully.

Settings to Check for Team Repositories

If setting up a team website under a GitHub Organization, verify these five configurations:

1. Member Permissions:

• Go to Organization Settings → Teams → select your team → ensure members have Write or Admin access.

2. Organization Actions Policy:

   • Go to Organization Settings → Actions → General → set policy to Allow all actions and reusable workflows.

3. Workflow Permissions:

   • Go to Repo Settings → Actions → General → Workflow permissions → select Read and write permissions.

4. Pages Deployment Source:

   • Go to Repo Settings → Pages → set the branch to gh-pages (do not use main).

5. Repository Visibility:

   • Go to Repo Settings → General → confirm visibility is Public (required for free GitHub Pages hosting).