Troubleshoot A Master Artificer GitHub Pages Issues

The site shows a 404 page

A 404 response from GitHub Pages means the server could not locate the file it was asked to serve. Work through these checks in order:1. Confirm GitHub Pages is enabled. Go to Settings → Pages in your repository. If no published URL is shown, GitHub Pages has not been enabled yet. Set the source to Deploy from a branch, choose main and / (root), and click Save.2. Confirm the source branch and folder are correct. Under Build and deployment, verify the branch is main and the folder is / (root). If either is wrong, correct it and save.3. Confirm index.html is at the repository root. Browse your repository on GitHub. index.html must appear in the top-level file list — not inside a subfolder. If it is inside a nested folder, move the files up one level.4. Check for an accidental double-nested folder. A common mistake when uploading is dragging the theme folder itself rather than its contents, which creates a structure like repository-name/a-master-artificer/index.html. If you see this, re-upload the theme files so index.html sits directly at the root.5. Wait for the first deployment to complete. After enabling Pages for the first time, the initial build can take one to two minutes. Refresh the Settings → Pages view to see whether a URL has been published yet.

The site is blank or missing styling

If the page loads but appears unstyled — plain text with no layout, colors, or fonts — the browser received the HTML but could not load the CSS and JavaScript assets.1. Confirm the assets/ folder was uploaded. Browse the repository on GitHub and check that an assets/ folder is present at the root. If it is missing, re-upload the theme and include the assets/ folder.2. Confirm file paths were not changed. The theme’s internal links are relative paths (for example, assets/main.css). If you renamed or moved the assets/ folder, the HTML files will no longer be able to find the stylesheet or scripts. Restore the original folder name and location.3. Check for capitalization mismatches. GitHub Pages runs on Linux, which treats filenames as case-sensitive. A path like Assets/main.css will fail if the folder is named assets/. Verify that folder and filenames in your repository match the paths referenced inside the HTML files exactly.4. Use the Network tab in DevTools. Open browser DevTools (F12), go to the Network tab, reload the page, and look for any requests shown in red (failed). The request URL will reveal whether the path is wrong or the file is missing.

Images do not load

Broken images usually mean the images/ folder was not uploaded, a filename does not match, or a path was changed.1. Confirm the images/ folder was uploaded. Open the repository on GitHub and check for an images/ folder at the root. If it is missing, upload it from the theme files.2. Confirm the images/screenshots/ subfolder is present. The README preview images and any screenshots referenced in the HTML are stored in images/screenshots/. If that subfolder is missing, the images will not load.3. Check screenshot filenames. The theme references screenshots by their exact filenames, such as a-master-artificer-screenshot-01.png. If you renamed any screenshot files, either restore the original filenames or update the matching src attributes inside the HTML files.4. Do not move images to a different folder. Moving images to a different location breaks the relative paths the HTML uses. Keep images inside images/ and images/screenshots/ unless you also update every reference in the HTML files.

The homepage does not load automatically

GitHub Pages automatically serves a file named exactly index.html when someone visits the root URL. Any variation in the filename will cause a 404 instead of the homepage.Check that the homepage file is named exactly index.html. Common problem filenames include:

Index.html       ← wrong capitalization
index.HTML       ← wrong extension case
default.html     ← wrong name entirely
home.html        ← wrong name entirely

The correct filename is:

index.html

Rename the file in your repository if the capitalization or name is wrong, then wait for Pages to republish.

The .nojekyll file looks empty

This is expected behavior — .nojekyll is supposed to be empty.The file’s filename is its entire instruction to GitHub Pages. When GitHub sees .nojekyll present in the repository root, it skips Jekyll processing and serves your static files directly. The file does not need any content.If you are seeing this flag because you expected some content to appear in the file, you can ignore it. The correct state is an empty file named exactly .nojekyll at the repository root.

Changes do not appear after committing

If you committed a change but the live site still shows the old version, check the following:1. Confirm you committed to the correct branch. Go to Settings → Pages and check which branch is set as the publishing source. If your commits went to a different branch (such as dev or feature/update), GitHub Pages will not pick them up.2. Confirm you edited the correct file. It is possible to edit one file and expect the change to appear in a different page. Double-check that the file you committed is actually the one referenced by the live page you are viewing.3. Allow one to two minutes for republishing. GitHub Pages does not update instantly. After a commit, the rebuild typically takes one to two minutes. Check the Settings → Pages view or the Actions tab for build status.4. Do a hard browser refresh. Your browser may be showing a cached version of the previous page. Force it to reload from the server:

Windows / Linux: Ctrl+Shift+R
macOS: Cmd+Shift+R

A hard refresh bypasses the local cache and requests fresh files from GitHub’s servers.

Navigation links return 404

If clicking a navigation link in the theme loads a 404, the most likely cause is a path or filename mismatch.1. Check that the linked HTML file exists. Navigation in this theme uses standard relative links (for example, pages/About.html). Open the repository on GitHub and confirm the file exists at the path the link points to.2. Check for capitalization mismatches. GitHub Pages is case-sensitive. A link to pages/about.html will 404 if the file is named pages/About.html. The filenames included with this theme use title case (e.g., About.html, Projects.html). If you renamed any pages, update all links that point to them.3. Understand how client-side routing works with this theme. The theme uses relative HTML file links rather than a client-side router that intercepts all URLs. This means navigation works through normal file requests, not through JavaScript-managed routes. Direct URL entry (typing a subpage URL into the address bar) works correctly because each page is a real .html file — as long as the file exists at the expected path.4. Do not remove index.html. index.html at the root is the fallback entry point for the site. Removing or renaming it breaks the base URL and can affect how the rest of the navigation resolves.

The custom cursor doesn't appear

The custom cursor effect is intentional and works as designed — but it only activates on desktop devices with a pointing device (mouse or trackpad).On touch screens and mobile devices, the custom cursor is hidden by design. Touch interfaces do not have a persistent cursor, so the custom cursor component disables itself automatically on those devices. This is expected behavior, not a bug.On desktop, if the cursor is not appearing:

Open browser DevTools (F12) and check the Console tab for any JavaScript errors that may have interrupted the cursor component from loading.
Confirm that assets/main.js loaded successfully in the Network tab.
Confirm that the components/grimoire/CustomCursor.js file is present in your repository and was uploaded as part of the theme.

The astrolabe nav button isn't visible

The astrolabe navigation button is positioned with fixed placement in the bottom-right corner of the viewport using fixed bottom-8 right-8 z-50.1. Scroll to the bottom-right of the page. On smaller screens or when the page is zoomed in, the button may appear to be off-screen. Scroll to the bottom-right corner of the viewport and check whether it is present but partially hidden.2. Check for z-index conflicts. If you have added custom elements with a z-index greater than 50, they may be covering the astrolabe button. Inspect the bottom-right area of the page with DevTools to see what element is on top.3. Confirm the component file was uploaded. Open your repository and verify that components/grimoire/AstrolabeNav.js is present. If the file is missing, re-upload the components/ folder from the theme.4. Check the Console for JavaScript errors. Open DevTools (F12) and look at the Console tab for any errors that may have prevented the component from rendering. A JavaScript error earlier in the page load can stop later components from initializing.

Overview

Pages & Structure

Components

Customization

Deployment