Skip to main content

Documentation Index

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

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

Most Artisan Developer deployment problems share a small set of root causes: incorrect file placement, missing folders, root-relative asset paths, or GitHub Pages settings that were not saved correctly. The sections below cover the most common issues and how to resolve each one.
A 404 error usually means GitHub Pages is not enabled, the source settings point to the wrong branch or folder, or index.html is not in the expected location.
  • Check that GitHub Pages is enabled in Settings → Pages.
  • Check that the source is set to the main branch and the / (root) folder — not a subfolder or a different branch.
  • Check that index.html is at the repository root, not inside a subfolder such as artisan-developer-github-pages-theme/index.html.
  • Check that the URL you are visiting matches the published URL pattern: 
    https://<username>.github.io/<repo-name>/
A blank page or a page with no styling usually means the assets/ folder was not uploaded, or the HTML files are referencing assets with root-relative paths that do not resolve correctly on GitHub Pages.
  • Confirm that the assets/ folder was uploaded to the repository and that it contains main.css and main.js.
  • Confirm that the components/ folder was uploaded alongside assets/.
  • Check that asset paths in the HTML files use relative paths, not root-relative paths:
    ✅ Correct❌ Incorrect
    ./assets/main.css/assets/main.css
    ./assets/main.js/assets/main.js
Root-relative paths starting with / do not resolve correctly unless the site is hosted at the root of a custom domain.
Broken images are almost always caused by a missing images/ folder in the repository, a filename capitalization mismatch, or a path that does not correctly point to the file.
  • Confirm the images/ folder was uploaded to the repository. Check that it appears at the repository root, not inside another folder.
  • Check filename capitalization — GitHub Pages is case-sensitive. A file named screenshot-01.png and a file named Screenshot-01.png are treated as two different files. The filename in the HTML src attribute must match the actual filename exactly.
  • Verify that image paths in the HTML files use relative paths rather than root-relative or absolute paths.
If the live site still shows an older version after you edited files, the changes may not have been committed to the correct branch, or the browser may be serving a cached copy.
  • Confirm the changes were committed to the main branch — the branch GitHub Pages is set to publish from. Commits to any other branch will not update the live site.
  • Check the Actions tab in the repository to see whether GitHub Pages has finished rebuilding. If a build is still in progress or failed, the live site will not yet reflect the new changes.
  • Hard-refresh the browser to bypass the local cache once the build is complete:
    • Mac: Cmd + Shift + R
    • Windows / Linux: Ctrl + Shift + R
Without a correctly placed .nojekyll file, GitHub Pages may fail to serve the JavaScript module files the theme depends on, causing the site to appear broken or unstyled even though all other files are in place.
  • The file must be named exactly .nojekyll — not nojekyll, .nojekyll.txt, or nojekyll.md. Any variation in the name will cause GitHub Pages to ignore it.
  • It must be at the repository root, beside index.html.
  • It is an empty file — it contains no content. Its presence in the repository is what matters, not what is inside it.
  • If the file is missing, create a new empty file in the repository root and name it .nojekyll, then commit the change and wait for GitHub Pages to rebuild.

​
Getting more help

If a problem is not covered here or the solutions above do not resolve the issue, report it using the repository issue form: Report an issue or request an addition To help resolve the issue as quickly as possible, include the following in your report:
  • Which page or URL was affected
  • The browser and device you were using
  • What happened (the actual behavior you observed)
  • What you expected to happen instead
  • A screenshot if one is available

Build docs developers (and LLMs) love

Get started for freeTalk to us