Skip to main content

Documentation Index

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

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

witch-dev uses hash-based routing — all URLs look like https://yoursite.com/#/about rather than https://yoursite.com/about. The fragment (#/about) is handled entirely in the browser by React Router; the server always receives a request for the same root path. This means you can deploy to any static host without configuring URL rewrite rules, _redirects files, or 404.html fallbacks. Drop the dist/ folder anywhere and it works.

​
GitHub Pages

GitHub Pages is the most natural home for witch-dev. The .nojekyll file is already committed to the repository, and the hash-routing strategy requires zero server configuration.
1

Push the repository to GitHub

If you haven’t already, initialize the repo and push to GitHub:
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/<username>/<repo>.git
git push -u origin main
2

Enable GitHub Pages in repository settings

  1. Go to your repository on GitHub.
  2. Click Settings → Pages (in the left sidebar under Code and automation).
  3. Under Source, select Deploy from a branch.
  4. Choose the branch (main) and folder (/ (root)) — or use the gh-pages branch with the dist/ directory if you prefer to keep built files on a separate branch.
  5. Click Save.
GitHub Pages will build and publish the site. The first deployment can take a minute or two.
3

Access your live site

Once published, your site is available at:
https://<username>.github.io/<repo>/
Navigate directly to https://<username>.github.io/<repo>/#/about, /#/projects, /#/skills, /#/writing, and /#/contact to confirm all routes load correctly.
If you deploy to a subdirectory path (e.g., https://user.github.io/witch-dev/), you must set the base option in vite.config.js before building. See the Configuration guide for details.
4

(Optional) Automate builds with GitHub Actions

Instead of manually running npm run build and committing the dist/ folder, use a GitHub Actions workflow to build and deploy automatically on every push to main. See the GitHub Actions workflow section below.

​
.nojekyll file

The .nojekyll file tells GitHub Pages to skip Jekyll processing entirely. Without it, GitHub Pages would attempt to process your output through Jekyll, which silently drops any file or directory whose name starts with an underscore — a problem because Vite outputs assets to dist/assets/ and generates chunk filenames that can include underscores.
The .nojekyll file is already present in the repository root. If you deploy the dist/ folder via GitHub Actions (using peaceiris/actions-gh-pages), the action copies this file automatically when you set publish_dir: ./dist. If you deploy the repo root directly, the root-level .nojekyll covers you.

​
GitHub Actions workflow

This workflow runs npm ci && npm run build on every push to main, then publishes the dist/ directory to the gh-pages branch using peaceiris/actions-gh-pages. GitHub Pages is then configured to serve from that branch. Create .github/workflows/deploy.yml in your repository: 
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '18'

      - run: npm ci && npm run build

      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist
peaceiris/actions-gh-pages automatically creates a .nojekyll file in the gh-pages branch root. No extra configuration is needed.
After adding this workflow file:
  1. Go to Settings → Pages → Source and switch the branch to gh-pages, folder / (root).
  2. Push any commit to main — the workflow runs, builds the site, and publishes dist/ to gh-pages.
  3. GitHub Pages serves the updated site within a minute.

​
Netlify

Netlify supports Vite out of the box. You can deploy in two ways: Drag-and-drop (no account setup required):
  1. Run npm run build locally.
  2. Go to app.netlify.com/drop.
  3. Drag the dist/ folder onto the upload zone.
  4. Netlify assigns a random URL (e.g., https://random-name-123.netlify.app) and deploys immediately.
Connect the repository for continuous deployment:
  1. Log in to Netlify → Add new site → Import an existing project.
  2. Connect your GitHub repository.
  3. Set the build settings:
    • Build command: npm run build
    • Publish directory: dist
  4. Click Deploy site.
Because witch-dev uses hash routing, you do not need to add a _redirects file or configure netlify.toml with rewrite rules. All routes resolve client-side.

​
Vercel

Vercel auto-detects Vite projects and configures the build pipeline automatically. Deploy via Vercel CLI: 
npm install -g vercel
vercel --prod
Vercel prompts you to confirm the project name and detected framework (Vite). It sets npm run build as the build command and dist as the output directory automatically. Deploy via Vercel dashboard:
  1. Go to vercel.com/new → import your GitHub repository.
  2. Vercel detects Vite and pre-fills the build configuration.
  3. Click Deploy.
Vercel’s edge network provides automatic HTTPS, global CDN distribution, and instant cache invalidation — all free on the Hobby plan for personal portfolio sites.

​
Custom domain

To use a custom domain (e.g., www.yourname.dev) with any static host: For GitHub Pages — add a CNAME file to the public/ directory in your source (Vite copies it to dist/ automatically): 
www.yourname.dev
Then configure your DNS provider to point your domain to GitHub Pages:
  • Add a CNAME record: www → <username>.github.io
  • Or use A records pointing to GitHub’s IP addresses for an apex domain.
Finally, enter your custom domain in Settings → Pages → Custom domain on GitHub. For Netlify and Vercel — add your domain through their dashboards (Site settings → Domain management). Both platforms provide automatic SSL via Let’s Encrypt.

Build docs developers (and LLMs) love

Get started for freeTalk to us