Deployment

@pagesmith/docs builds a fully static site — HTML, CSS, JS, and search index. The output can be hosted on any static file server. This guide covers deployment to common platforms and the configuration options that affect how your site is served.

Build Output

Running pagesmith-docs build produces a self-contained directory (default: gh-pages/) with the following structure:

1gh-pages/2  index.html              # Home page3  404.html                # GitHub Pages-compatible 4044  .nojekyll               # Prevents GitHub Pages from ignoring _-prefixed dirs5  sitemap.xml             # Auto-generated sitemap (when origin is set)6  robots.txt              # Auto-generated if not in publicDir7  assets/8    style.a1b2c3d4.css    # Bundled theme CSS (content-hashed)9    main.e5f6g7h8.js      # Bundled runtime JS (content-hashed)10    diagram.i9j0k1l2.svg  # Content images (flat, content-hashed)11    fonts/                # Bundled Open Sans + JetBrains Mono (woff2)12  pagefind/               # Search index (when search is enabled)13  guide/14    getting-started.html  # /guide/getting-started15    ...

By default (trailingSlash: false), every page is written as <slug>.html, so requesting /guide/getting-started resolves directly on GitHub Pages without a 301 redirect. Set trailingSlash: true in pagesmith.config.json5 to use <slug>/index.html instead.

Content images are published as flat name.hash.ext files under /assets/ rather than preserving the content directory structure. The content hash in the filename enables long-lived browser caching.

The .nojekyll file is always generated to prevent GitHub Pages from ignoring the _-prefixed pagefind/ directory.

basePath Configuration

The basePath setting controls the URL prefix for your site. This is required when deploying to a subdirectory (e.g. https://user.github.io/my-project/).

1{2  basePath: "/my-project",3}

The base path follows a priority resolution order:

1. --base-path CLI flag (highest priority)
2. BASE_URL environment variable
3. basePath in pagesmith.config.json5
4. Auto-detected from git remote URL (repo name as base path)
5. Default: "/" (root)

This resolution chain allows CI/CD pipelines to override the base path without modifying the config file.

When to set basePath

• GitHub Pages project site (user.github.io/repo-name): set basePath: '/repo-name'
• GitHub Pages user site (user.github.io): leave as default "/"
• Custom domain: leave as default "/" unless your docs live under a subdirectory
• Netlify / Vercel / Cloudflare: leave as default "/" for most setups

The pagesmith-docs init command auto-detects the correct basePath from your git remote URL when running in a GitHub Pages context.

GitHub Pages

GitHub Pages is the default deployment target. The build output includes everything needed: .nojekyll, 404.html, and a sitemap.xml.

Configuration

1{2  name: "My Project",3  origin: "https://username.github.io",4  basePath: "/my-project",5  outDir: "./gh-pages",6}

GitHub Actions Workflow

Create .github/workflows/deploy.yml:

1name: Deploy docs23on:4  push:5    branches: [main]67permissions:8  contents: read9  pages: write10  id-token: write1112concurrency:13  group: pages14  cancel-in-progress: false1516jobs:17  build:18    runs-on: ubuntu-latest19    steps:20      - uses: actions/checkout@v421        with:22          fetch-depth: 0 # Required for lastUpdated timestamps2324      - uses: actions/setup-node@v425        with:26          node-version: 242728      - run: npm ci29      - run: npx pagesmith-docs build3031      - uses: actions/upload-pages-artifact@v532        with:33          path: gh-pages3435  deploy:36    needs: build37    runs-on: ubuntu-latest38    environment:39      name: github-pages40      url: ${{ steps.deployment.outputs.page_url }}41    steps:42      - id: deployment43        uses: actions/deploy-pages@v5

The fetch-depth: 0 is important — without full git history, the lastUpdated timestamps will be missing or incorrect.

Manual Deployment

If you prefer to deploy from a branch instead of Actions:

1npx pagesmith-docs build2cd gh-pages3git init4git add -A5git commit -m "deploy"6git push -f git@github.com:username/repo.git main:gh-pages

Then configure the repository to deploy from the gh-pages branch in Settings > Pages.

Netlify

Netlify works well with Pagesmith since the output is fully static.

Build Settings

In your Netlify dashboard or netlify.toml:

1[build]2  command = "npx pagesmith-docs build --out-dir dist"3  publish = "dist"45[build.environment]6  NODE_VERSION = "24"

When deploying to https://my-project.netlify.app/ (the root), leave basePath as default. The --out-dir dist override is optional but avoids Netlify confusion with the gh-pages/ default.

SPA-style 404 Handling

Pagesmith already generates a 404.html at the build root. Netlify automatically serves this for missing routes. If you want to add redirects for legacy URLs, create a _redirects file in your public/ directory:

1/old-path    /new-path    3012/docs/*      /guide/:splat 301

Files in publicDir (default: public/) are copied as-is to the build output.

Vercel

Project Configuration

Create vercel.json in your project root:

1{2  "buildCommand": "npx pagesmith-docs build --out-dir dist",3  "outputDirectory": "dist",4  "cleanUrls": true5}

The cleanUrls setting tells Vercel to serve path.html files for clean /path URLs. No trailingSlash setting is needed because Pagesmith’s default output format (path.html) already matches Vercel’s cleanUrls behavior. If you set trailingSlash: true in your pagesmith.config.json5, also add "trailingSlash": true to vercel.json.

Framework Preset

In the Vercel dashboard, set the framework preset to Other and configure:

• Build Command: npx pagesmith-docs build --out-dir dist
• Output Directory: dist
• Install Command: npm ci

Since Pagesmith sites are fully static, no serverless functions or edge middleware are needed.

Cloudflare Pages

Dashboard Setup

In the Cloudflare Pages dashboard:

• Build command: npx pagesmith-docs build --out-dir dist
• Build output directory: dist
• Node.js version: Set NODE_VERSION environment variable to 24

wrangler.toml

Alternatively, configure via wrangler.toml:

1name = "my-docs"2compatibility_date = "2024-01-01"34[site]5bucket = "./dist"

Cloudflare Pages automatically handles 404 routing when a 404.html file exists at the build root.

Custom Domain Setup

origin Configuration

Set the origin field to your production URL. This affects canonical links, OpenGraph tags, and sitemap URLs:

1{2  origin: "https://docs.my-project.com",3  basePath: "/",4}

The origin should be the scheme + host without a trailing slash.

CNAME for GitHub Pages

If using a custom domain with GitHub Pages, add a CNAME file to your public/ directory:

1docs.my-project.com

This file is copied to the build output automatically and tells GitHub Pages to serve on the custom domain.

DNS Configuration

Point your domain to the hosting platform:

For apex domains (no subdomain), use A records or ALIAS records as documented by each platform.

Environment Variables

These environment variables affect the build:

Example in a CI pipeline:

1BASE_URL=/my-project npx pagesmith-docs build

Post-Deployment Checklist

After deploying, verify:

1. Home page loads with correct styles and fonts
2. Navigation links work and point to correct paths (check basePath)
3. Search opens with Ctrl+K / Cmd+K and returns results
4. 404 page renders for unknown routes
5. sitemap.xml is accessible at <origin><basePath>/sitemap.xml
6. External links open in new tabs
7. Code blocks render with syntax highlighting in both light and dark mode
8. Edit links (if enabled) point to the correct repository and branch

Troubleshooting Deployments

Pages load without styles

The most common cause is a missing or incorrect basePath. If your site is at https://user.github.io/repo/ but basePath is not set, all asset paths will resolve to the wrong location. Set basePath: '/repo' in your config.

Search returns no results

Pagefind requires the pagefind/ directory to be present in the build output. If search is enabled but the Pagefind binary fails during build, you will see a warning in the build log. Ensure pagefind is installed as a dependency (it is included with @pagesmith/docs).

404 page not styled on GitHub Pages

GitHub Pages serves 404.html from the repository root. The build generates both 404/index.html and 404.html at the output root to cover both GitHub Pages and directory-based hosting.

lastUpdated shows wrong dates

Git timestamps require full history. In CI, use fetch-depth: 0 in your checkout step. Shallow clones will either show no date or the clone date.