Skip to main content

Documentation Index

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

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

Digital Alchemy’s pages/ directory contains a static HTML file for every route in the app. Each file loads the same JavaScript bundle as index.html and includes a small bootstrap script that sets the correct hash before React mounts, enabling direct URL navigation and bookmark support on GitHub Pages without any server-side configuration.

​
The problem

GitHub Pages serves static files from a repository. When a user visits https://user.github.io/digital-alchemy/about directly — via a bookmark, a shared link, or a browser refresh — GitHub Pages looks for a file at about/index.html on disk. That file doesn’t exist, so GitHub Pages returns a 404 Not Found. This is a fundamental constraint of any static hosting provider that doesn’t support server-side URL rewriting. Without a solution, only the root URL (/) would work for direct navigation — every other route would 404.

​
The solution: per-route static HTML files

Each route in Digital Alchemy has a corresponding HTML file in the pages/ directory. These files are full copies of index.html — they load the same JavaScript bundle — but they include a small <script> block that:
  1. Sets window.__STATIC_PAGE_ROUTE__ to the route path (for debugging / detection).
  2. Sets window.location.hash to the correct route hash if it isn’t already set.
Because the app uses HashRouter, setting window.location.hash = "/about" is equivalent to navigating to /#/about. The React app boots up, reads the hash, and renders the correct view — all without any server involvement.

​
The pattern

Here is the exact script from pages/About.html: 
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>About | digital-alchemy</title>
    <script type="module" crossorigin src="../assets/main.js"></script>
    <link rel="stylesheet" crossorigin href="../assets/main.css">
    <script>
      window.__STATIC_PAGE_ROUTE__ = "/about";
      if (!window.location.hash || window.location.hash === "#/" || window.location.hash === "#") {
        window.location.hash = "/about";
      }
    </script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>
The if condition ensures the hash is only overwritten when it is empty or set to the root — so if a user navigates directly to pages/About.html#/contact, their explicit hash is preserved rather than being forced to /about.

​
List of static pages

FileRoutePage name
pages/About.html/aboutThe Witch
pages/Projects.html/projectsSummonings
pages/Skills.html/skillsFamiliar Languages
pages/Work.html/workLineage
pages/CaseStudies.html/case-studiesGrimoire
pages/Articles.html/articlesForbidden Knowledge
pages/Testimonials.html/testimonialsThe Coven
pages/Contact.html/contactCast a Message
The root route (/) is covered by index.html at the repository root — no additional static file is needed for it.

​
How to add a static page for a new route

1

Add the route to React Router

Register the new route in assets/main.js following the existing pattern:
<Route path="/new-section" element={<NewSectionView />} />
Also add a corresponding entry to the navItems array in components/Layout.js.
2

Create the static HTML file

Create a new file in pages/ — for example pages/NewSection.html. Copy the structure from any existing file in pages/ and update the three values:
  • <title> — the page title
  • window.__STATIC_PAGE_ROUTE__ — the route path string
  • window.location.hash — the same route path string
<script>
  window.__STATIC_PAGE_ROUTE__ = "/new-section";
  if (!window.location.hash || window.location.hash === "#/" || window.location.hash === "#") {
    window.location.hash = "/new-section";
  }
</script>
3

Include the file in the build

When running npm run build, copy the updated pages/ directory into dist/ so the static file is deployed alongside the built app:
cp -r pages/ dist/pages/
Because Digital Alchemy uses HashRouter, all actual navigation within the app happens entirely on the client side — React Router intercepts hash changes and renders the correct view without any network request. The static HTML files in pages/ are only needed for the very first load when a user arrives at a deep URL. Once the app is running, clicking nav links uses hash-based routing with no page reloads.

​
Why not use a 404.html redirect?

A common GitHub Pages workaround is to create a 404.html that redirects all unknown URLs back to index.html with the path encoded in the query string. Digital Alchemy uses explicit per-route files instead because:
  • No redirect flash — users land directly on the correct HTML file rather than seeing a momentary 404 page.
  • Correct HTTP status — pages/About.html returns 200 OK, not 404. This matters for SEO crawlers and link preview scrapers.
  • Explicit control — each page can have its own <title> tag for accurate browser tab labels and history entries.

Build docs developers (and LLMs) love

Get started for freeTalk to us