Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/apursley2012/welcome-mortals/llms.txt

Use this file to discover all available pages before exploring further.

Most Welcome, Mortals problems on GitHub Pages come down to one of three root causes: a file is missing, a file is in the wrong location, or GitHub Pages is pointed at the wrong source. The sections below cover every common symptom with a checklist of what to verify. Work through the relevant checklist top to bottom — the first item that doesn’t match is usually the fix.
Before working through any checklist, open your browser’s DevTools (press F12 or Cmd+Option+I on macOS), switch to the Network tab, and reload the page. The Network tab shows every resource the browser tries to load and highlights the ones that fail in red. This instantly tells you which files are missing or returning errors, saving significant guesswork.
GitHub Pages can take up to a minute to publish after a commit. If you just pushed a change and the live site looks stale, wait 60 seconds and perform a hard refresh (Ctrl+Shift+R on Windows and Linux, Cmd+Shift+R on macOS) before assuming something is broken. A normal page refresh may serve a cached version of the old page.

​
Problem Checklists

Symptom: Visiting your GitHub Pages URL returns a 404 error page instead of the Welcome, Mortals homepage.Check each of the following:
  1. GitHub Pages is enabled. Open your repository on GitHub, go to Settings → Pages, and confirm that a source branch and folder are configured. If the Pages section shows no active deployment, Pages has not been turned on.
  2. The source is set to the correct branch and folder. The setting should show: 
    Branch: main
Folder: / (root)
    If the folder is set to /docs or any path other than / (root), GitHub Pages will look for files in the wrong location.
  3. index.html is at the repository root. Browse to the repository home page on GitHub. You should see index.html listed directly in the root file list, not inside a subfolder.
  4. Files were not uploaded inside an extra subfolder. If you dragged the theme folder itself (rather than its contents) into the upload area, all files will be nested one level too deep. The path welcome-mortals-github-pages-theme/index.html does not satisfy GitHub Pages — the path must be index.html.
  5. The repository name in the URL is correct. Your live URL is https://<username>.github.io/<repo-name>/. Check that <repo-name> in the URL exactly matches your repository name on GitHub, including capitalization.
Symptom: The homepage loads but appears completely unstyled — no colors, no layout, no themed typography — or the page is entirely blank.Check each of the following:
  1. The assets/ folder was uploaded. The theme stylesheet (assets/main.css) and supporting scripts live in assets/. If this folder is missing, the page will have no styling. Browse to your repository root and confirm assets/ appears in the file list.
  2. The components/ folder was uploaded. Shared interactive theme files — including the layout component — live in components/. A missing components/ folder can cause the page to appear blank or broken. Confirm components/ appears at the repository root.
  3. File paths were not changed after uploading. The HTML files reference assets/ and components/ using relative paths. If either folder was renamed or moved, those paths break. Folder names must match exactly: assets/ and components/, not Assets/, CSS/, or any other variation.
  4. Filenames and capitalization match exactly. GitHub Pages paths are case-sensitive. A file named main.css cannot be referenced as Main.css. If any file was renamed during upload, the path reference will fail silently in some browsers and loudly in the Network tab of DevTools.
Symptom: The site loads with correct styling and layout, but some or all images are broken — showing a missing-image icon or a blank space.Check each of the following:
  1. The images/ folder was uploaded. Browse to your repository root and confirm the images/ folder appears in the file list. If it was left out during the upload, all image references will fail.
  2. Image filenames and paths match exactly. GitHub Pages is case-sensitive. An image stored as welcome-mortals-screenshot-01.PNG cannot be loaded via the path welcome-mortals-screenshot-01.png (lowercase .png). Check that the filenames in the images/ folder on GitHub exactly match the paths referenced in your HTML files.
  3. .PNG capitalization has not been changed. The theme’s screenshot files use uppercase .PNG extensions. If your operating system or image editor saved a replacement image with a lowercase .png extension, the reference will break on GitHub Pages even though it may have worked on your local machine (macOS and Windows file systems are case-insensitive; GitHub Pages is not).
The DevTools Network tab is particularly useful for image problems. Any image that fails to load will appear in red with a 404 status, and the full requested path will be shown — making it easy to spot a capitalization mismatch.
Symptom: Visiting the root URL (https://<username>.github.io/<repo-name>/) shows a 404 or a directory listing instead of the Welcome, Mortals homepage.Cause: GitHub Pages automatically serves a file named index.html when a visitor loads the root URL. If the homepage file has been renamed, GitHub Pages cannot find it.Confirm that the homepage file is named exactly:
index.html
Common renaming mistakes that break automatic homepage loading:
# Correct
index.html

# Incorrect — none of these are served automatically
home.html
Index.html
index.HTML
homepage.html
If the file was renamed, rename it back to index.html and commit the change.
Symptom: You opened .nojekyll and the file appears to contain nothing at all.This is correct behavior — no action is needed..nojekyll is intentionally empty. Its presence in the repository root is the signal; its content is irrelevant. The empty file tells GitHub Pages to skip Jekyll processing and serve the theme files directly as static assets. If .nojekyll contained text, that text would be ignored.What matters is that the file:
  • Exists at the repository root (beside index.html)
  • Is named exactly .nojekyll
# Correct — empty file, exact name
.nojekyll

# Incorrect — wrong names, even if also empty
nojekyll
.nojekyll.txt
nojekyll.md
If .nojekyll is missing entirely, add it back as an empty file at the repository root.
Symptom: You committed a change to the repository but the live GitHub Pages site still shows the old version.Check each of the following:
  1. The change was committed to the publishing branch. GitHub Pages only republishes when the branch it is configured to watch receives a new commit. Go to Settings → Pages and confirm which branch is selected. If you committed to a different branch, switch to the publishing branch and commit the change there.
  2. The correct file was edited. If the repository has similarly named files in different folders, it is possible to edit the wrong one. Confirm the file you edited is the one referenced by the page you are trying to update.
  3. The browser is serving a cached copy. A normal page refresh (F5 or Cmd+R) may load the cached version. Perform a hard refresh — Ctrl+Shift+R on Windows and Linux, or Cmd+Shift+R on macOS — to force the browser to fetch fresh files from GitHub Pages.
  4. The live URL matches the repository name. If the URL you are checking does not match your actual repository name, you may be looking at the wrong site (or a cached version of a previous deployment). Confirm the URL is https://<username>.github.io/<exact-repo-name>/.
  5. The deployment has not finished yet. GitHub Pages typically publishes within a minute of a commit, but it can occasionally take longer. Check the Actions tab of your repository to see whether the Pages deployment workflow is still running or has completed.

​
Still Stuck?

If none of the checklists above resolve the problem, the repository includes issue templates for reporting bugs and requesting help.

Report a Bug

Use the bug report template to describe what happened, which page is affected, and what browser or device you are using.

GitHub Pages Deployment Guide

Review the full step-by-step deployment guide to confirm every setup step was completed correctly.

Build docs developers (and LLMs) love

Get started for freeTalk to us