Deploying — Sourcey

sourcey build writes static HTML to a directory. No server, no runtime, no build step on the hosting side. Upload the files and you're done.

sourcey build -o dist

Hosting options

GitHub Pages

Push the output directory to a gh-pages branch or configure GitHub Actions to build and deploy. Free for public repos.

Netlify

Drop the output directory into a Netlify site. Set the build command to npx sourcey build and the publish directory to dist.

Vercel

Same approach as Netlify. Build command: npx sourcey build. Output directory: dist.

S3 / CloudFront

Upload the output to an S3 bucket with static website hosting enabled. Add CloudFront for HTTPS and caching.

GitHub Actions

The sourcey/build-docs action handles the build step for you:

name: Deploy Docs
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: sourcey/build-docs@v1
        with:
          output: dist
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Or install manually if you prefer more control:

name: Deploy Docs
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install
      - run: npx sourcey build -o dist
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

[build]
  command = "npx sourcey build"
  publish = "dist"

{
  "buildCommand": "npx sourcey build",
  "outputDirectory": "dist"
}

Clean URLs

By default, sourcey emits foo.html and links carry the .html suffix. Set prettyUrls in sourcey.config.ts to strip the extension:

export default defineConfig({
  prettyUrls: "slash", // "/foo/" - works on any static host
  // or
  prettyUrls: "strip", // "/foo"  - needs extensionless HTML support
  navigation: { tabs: [/* ... */] },
});

"slash" writes each page as foo/index.html, which every static host serves at /foo/ automatically. "strip" writes each page as foo.html and links to /foo; use it on hosts that serve extensionless HTML paths.

Host Notes

Cloudflare Pages serves foo.html at /foo, so prettyUrls: "strip" is a good fit. Vercel supports the same public URL style with cleanUrls: true:

{
  "buildCommand": "npx sourcey build",
  "outputDirectory": "dist",
  "cleanUrls": true
}

For simple static hosts that do not serve foo.html at /foo, use prettyUrls: "slash" instead.

Sitemap

Every build generates a sitemap.xml in the output directory. Submit it to Google Search Console or add it to your robots.txt:

Sitemap: https://docs.example.com/sitemap.xml

Subfolder deployment

To serve docs under a path like /docs/ on an existing site, build the output into that subfolder of your static directory:

sourcey build -o ./public/docs

The output is self-contained with relative asset paths. It works in any subdirectory without configuration changes.

Embeddable output

The --embed flag produces HTML without the <html>, <head>, and <body> wrappers. This is useful for embedding sourcey output in an iframe or injecting it into an existing page.

sourcey build --embed -o ./embed

Tip

Committing built output to your repo is a valid deployment strategy. It means zero build step on the hosting side and guarantees the deployed site matches what you reviewed locally.

For a detailed walkthrough of embedding docs in an existing site, see the Embedding guide. For all build flags, see sourcey build.