Deploy

Raw Markdown View this page on GitHub

Deploy

docpages -o site docs writes a static site. Upload site/ to any static host.

Build in CI

Build on every push to main:

go run github.com/romshark/docpages/cmd/docpages@latest -o site docs

1 build writes every version, so nothing needs to carry over between builds. A build first deletes what the last one wrote in site/: the version folders, index.html, llms.txt, sitemap.xml and 404.html. It leaves other files alone.

The build reads releases from the Git tags. actions/checkout of GitHub Actions fetches 1 commit and no tags by default. Fetch all of them:

.github/workflows/pages.yml
- uses: actions/checkout@v7
  with:
    fetch-depth: 0

URLs without .html

Pages link each other without .html, as get-started/install for get-started/install.html. GitHub Pages serves these as they are. Other hosts may need a rule that serves /a/b from /a/b.html. The rule must also cover a name with a dot, as /guide/v1.2-notes for /guide/v1.2-notes.html.

Below a landing page

To put the docs below a landing page, build them into a subfolder:

docpages -o public/docs docs

Then point the logo back to the landing page with home, relative to the output folder:

docs/README.md
---
home: ../
---