Skip to main content

Documentation Index

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

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

GitHub Pages serves static files directly from a repository branch — which is exactly what Sys.Witch V2 is built for. The pre-compiled assets/ bundles, the root-level index.html, the pages/ subfolder, and the .nojekyll file are everything GitHub Pages needs. No build configuration, no workflow YAML, and no _config.yml are required. Follow the four steps below and your portfolio will be live at a public URL within minutes of uploading.

​
Required Repository Structure

index.html must sit at the root of the repository — not inside a subfolder. GitHub Pages looks for index.html at the top level of the selected source branch. If it is nested one level deeper, the site will return a 404. Correct — index.html at repository root: 
your-repo/
├── .nojekyll
├── index.html
├── assets/
│   ├── main.css
│   └── main.js
├── components/
├── data/
└── pages/
    ├── About.html
    ├── CaseStudies.html
    ├── Contact.html
    ├── Projects.html
    ├── Skills.html
    └── Writing.html
Incorrect — index.html buried inside a subfolder: 
your-repo/
└── sys.witch-v2/
    ├── index.html
    ├── assets/
    └── components/
When uploading from a downloaded ZIP, extract the ZIP first, then upload the contents of the extracted folder — not the folder itself.

​
Deploy Your Portfolio

1

Create a GitHub repository

  1. Sign in to github.com.
  2. Select the + icon in the top-right corner.
  3. Select New repository.
  4. Enter a repository name (for example: portfolio or sys-witch).
  5. Set the repository to Public. GitHub Pages is available on public repositories under all plan types.
  6. Leave Initialize this repository unchecked — you will upload files in the next step.
  7. Select Create repository.
2

Upload the theme files

  1. Open the empty repository you just created.
  2. Select Add file → Upload files.
  3. Open your local sys.witch-v2 folder and select all of its contents — including hidden files if your OS shows them (.nojekyll starts with a dot).
  4. Drag the selected files and folders into the GitHub upload area.
  5. Verify in the file list that index.html appears at the top level, not nested inside another folder.
  6. Confirm that .nojekyll, the assets/ folder, and the pages/ folder were included.
  7. Enter a commit message such as Initial theme upload.
  8. Select Commit changes.
GitHub’s web uploader does not show hidden files like .nojekyll in the preview list, but it will upload them if they were selected. After committing, browse the repository file list and confirm .nojekyll appears at the root.
3

Enable GitHub Pages

  1. Open the repository on GitHub.
  2. Select Settings from the top navigation bar.
  3. Select Pages from the left sidebar.
  4. Under Build and deployment, set the source to Deploy from a branch.
  5. Set the branch and folder: 
    Branch: main
Folder: / (root)
  6. Select Save.
GitHub will begin building the site. A banner at the top of the Pages settings screen will update when the deployment is complete — usually within one to two minutes.
4

Verify the live URL

Once GitHub Pages finishes deploying, your portfolio is live at:
https://<username>.github.io/<repo-name>/
For example, if your GitHub username is alysha and your repository is named portfolio:
https://alysha.github.io/portfolio/
Open the URL and test the homepage, the navigation bar, the particle field background, the Projects and Skills pages, and the Contact form. Confirm that images and stylesheets load correctly before sharing the link.

​
Updating the Published Site

Committed changes to the main branch are republished automatically. GitHub Pages re-deploys within seconds to a couple of minutes after each commit. To update a file through the GitHub web interface:
  1. Open the repository on GitHub.
  2. Navigate to the file you want to edit.
  3. Select the pencil-shaped Edit this file icon (top-right of the file view).
  4. Make your changes.
  5. Select Commit changes and enter a brief description.
  6. Wait one to two minutes, then hard-refresh the live URL (Ctrl+Shift+R / Cmd+Shift+R) to see the update.
To update by pushing from a local clone: 
# Make your edits locally, then:
git add .
git commit -m "Update projects and contact info"
git push origin main

​
Important Files Reference

​
index.html

The homepage and GitHub Pages entry point. It must remain at the repository root. GitHub Pages resolves the base URL https://<username>.github.io/<repo-name>/ by looking for index.html — a file named home.html or default.html will not be found automatically.

​
.nojekyll

An empty file stored beside index.html. The filename is the entire instruction — it signals to GitHub Pages that the repository should be served as plain static files, bypassing the Jekyll processor. If Jekyll processes the repository, the JavaScript bundles in assets/ may be stripped or ignored. The .nojekyll file must be:
  • Named exactly .nojekyll (dot prefix, no extension)
  • Located at the repository root
  • Completely empty (zero bytes)

​
Why _config.yml Is Not Needed

Sys.Witch V2 does not use Jekyll. The assets/main.css and assets/main.js bundles are pre-compiled and require no processing pipeline. Adding a _config.yml is unnecessary and could introduce unexpected behavior. Keep .nojekyll at the root and publish from main and /(root).

​
Common Problems

Check each of the following:
  1. GitHub Pages is enabled under Settings → Pages.
  2. The selected source branch is main and the folder is /(root).
  3. index.html is at the repository root, not inside a subfolder.
  4. The files were not uploaded inside an unnecessary second folder layer (for example sys.witch-v2/sys.witch-v2/).
  5. The repository name in your browser URL matches the repository name on GitHub exactly — including capitalization.
After enabling Pages for the first time, allow up to two minutes for the initial deployment to complete before the URL becomes active.
If the page loads but appears unstyled or completely white:
  1. Open your browser’s developer console (F12 → Console) and check for 404 errors on asset files.
  2. Confirm that the entire assets/ folder was uploaded, including main.css and main.js.
  3. Confirm that components/, data/, and pages/ folders were uploaded — the pre-compiled scripts reference these paths at runtime.
  4. Verify that file paths were not changed after uploading. Internal paths are relative and case-sensitive on GitHub Pages.
  5. Check that filenames have not been accidentally renamed or that capitalization has not changed — Main.css and main.css are treated as different files.
If project or background images fail to load:
  1. Confirm that the images/ folder was included in the upload.
  2. Check that image filenames and folder paths match exactly what is referenced in the data/ files and HTML.
  3. Filename capitalization matters — Screenshot-01.png and screenshot-01.png are different files on GitHub Pages’ Linux servers.
  4. After renaming or replacing an image, commit the change and wait for re-deployment before testing.
GitHub Pages serves index.html automatically when a visitor opens the root URL. If the homepage does not load:
  1. Confirm the homepage file is named exactly index.html — not Index.html, home.html, or any other variation.
  2. Confirm index.html is at the repository root, not inside a subfolder.
  3. Confirm GitHub Pages is configured to deploy from main and /(root).
Yes, that is correct and expected. The .nojekyll file is supposed to be completely empty. Its presence at the repository root is the signal; its contents are irrelevant. Do not add text, comments, or any content to it. Keeping it empty is the right behavior.
GitHub Pages re-deploys automatically after each commit, but it is not instant. Try the following:
  1. Wait one to two minutes after committing before checking the live URL.
  2. Hard-refresh the page (Ctrl+Shift+R on Windows/Linux, Cmd+Shift+R on macOS) to bypass the browser cache.
  3. Confirm the commit was pushed to the main branch — commits to other branches will not trigger a re-deploy unless Pages is configured to use that branch.
  4. Open Settings → Pages and check whether GitHub shows a recent deployment timestamp or an error message.
  5. Confirm you edited the correct file. If two similar files exist in the repository, it is easy to edit one while the page renders the other.
GitHub Pages paths are case-sensitive. A link to pages/projects.html will return a 404 if the file is named pages/Projects.html. Use filenames that match exactly in every internal link and navigation reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us