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.

Welcome, Mortals is designed for zero-config GitHub Pages deployment — there is no build step, no bundler to run, and no configuration files to create. The theme is made of static HTML, CSS, and JavaScript files that GitHub Pages can serve directly. Upload the files, point GitHub Pages at the root of your repository, and your portfolio is live.

​
Required Repository Structure

For GitHub Pages to serve the theme correctly, index.html must sit at the root of your repository — not inside a subfolder. When you extract the downloaded theme archive, all of the top-level contents must land directly in the repository root, not nested inside a second copy of the theme folder. 
your-repo/
├── .nojekyll
├── index.html
├── assets/
├── components/
└── images/
If your files land inside a nested subfolder, GitHub Pages will serve a 404 instead of your homepage. Drag the contents of the extracted archive into the upload area, not the folder itself.

​
Upload the Theme Files

1

Create or open your repository

Log in to GitHub and create a new repository, or open an existing one where you want to host the theme. The repository can be public or private (GitHub Pages is available on both for personal accounts).
2

Open the file upload panel

On the repository home page, select Add file, then select Upload files.
3

Drag the extracted theme contents into the upload area

Open the extracted theme folder on your computer. Select all of the files and folders inside it — .nojekyll, index.html, assets/, components/, images/, and any other root-level files — then drag them into the GitHub upload area. Do not drag the outer theme folder itself; drag its contents.
4

Confirm the file list before committing

Before committing, verify that the upload list shows:
  • index.html at the top level
  • .nojekyll at the top level
  • assets/ folder
  • components/ folder
  • images/ folder
5

Commit the upload

Add a commit message (for example, Add Welcome, Mortals theme files) and select Commit changes. GitHub will process the upload and add all files to the repository root.

​
Enable GitHub Pages

1

Open repository Settings

On the repository home page, select the Settings tab at the top of the page.
2

Open the Pages section

In the Settings sidebar, select Pages under the Code and automation group.
3

Configure the source

Under Build and deployment, set the source to Deploy from a branch, then choose:
Branch: main
Folder: / (root)
4

Save the configuration

Select Save. GitHub Pages will queue the first deployment. This usually takes under a minute.
5

Confirm the published URL

Reload the Pages settings page. GitHub will display the live URL at the top of the section once the site is published. Visit the URL to confirm the homepage loads.

​
Confirm the Published URL

Your live site URL follows this pattern: 
https://<username>.github.io/<repo-name>/
For example, a repository named my-portfolio under the account jsmith is published at: 
https://jsmith.github.io/my-portfolio/
Open the URL and test the homepage, themed cursor, navigation links, images, and styling. If anything looks missing, work through the Troubleshooting guide.

​
Updating the Published Site

Committed changes to the publishing branch are republished automatically — there is no manual redeploy step.
1

Open the file to edit

On the repository home page, browse to the file you want to update and select it to open the file view.
2

Open the editor

Select the pencil-shaped Edit this file button in the top-right corner of the file view.
3

Make your changes

Edit the file content directly in the GitHub editor.
4

Commit the changes

Scroll to the bottom of the editor page, add a commit message, and select Commit changes. GitHub Pages will detect the commit and republish the site automatically.
5

Verify the update

Wait a moment for the deployment to complete, then reload the live URL. If the browser is serving a cached copy of the old page, perform a hard refresh (Ctrl+Shift+R on Windows and Linux, Cmd+Shift+R on macOS).
GitHub Pages typically republishes within a minute of a new commit, but it can occasionally take a few minutes during high-traffic periods. Wait and hard-refresh before assuming something is broken.

​
Important GitHub Pages Files

​
index.html

index.html is the homepage and the GitHub Pages entry file. GitHub Pages automatically serves index.html when a visitor loads the root URL of your site. It must remain at the repository root and must be named exactly index.html.
Do not rename index.html to home.html or any other name. GitHub Pages will not automatically serve a file named anything other than index.html as the homepage, and visitors will see a 404 instead.

​
.nojekyll

.nojekyll is an empty file stored alongside index.html at the repository root. Its presence tells GitHub Pages to skip Jekyll processing and serve the theme files directly. The filename itself is the instruction — the file should contain no content at all.
If you open .nojekyll and it appears blank, that is correct. It is supposed to be completely empty.
The file must be named exactly .nojekyll. Common naming mistakes that break this behavior: 
# Correct
.nojekyll

# Incorrect — none of these work
nojekyll
.nojekyll.txt
nojekyll.md

​
Why _config.yml Is Not Required

Some GitHub Pages guides mention creating a _config.yml or config.yaml file. Welcome, Mortals does not require either. The .nojekyll file at the repository root tells GitHub Pages to skip Jekyll entirely, so no Jekyll configuration is needed. Adding a _config.yml is unnecessary and could interfere with the direct static file serving the theme relies on.

Build docs developers (and LLMs) love

Get started for freeTalk to us