GuideHow-to recipes
Deploy to GitHub Pages
Build a Douze site in GitHub Actions with the install script and deploy it with actions/deploy-pages.
GitHub Pages serves a site that a GitHub Actions workflow builds and uploads. The workflow below installs Douze with
its install script, builds the site of the docs folder, and deploys its output folder. This documentation site is
deployed the same way.
Enable PagesLink to this heading
In the repository's Settings > Pages, set Source to GitHub Actions.
Add the workflowLink to this heading
name: Deploy site
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Install douze
run: |
curl -fsSL https://raw.githubusercontent.com/sebastienros/douze/main/install.sh | sh -s -- --preview --no-modify-path
echo "$HOME/.douze/bin" >> "$GITHUB_PATH"
- name: Build
run: douze -s docs -o docs/_site
- uses: actions/upload-pages-artifact@v5
with:
path: docs/_site
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v5
What each part does:
- Install douze: the install script downloads the native build for the runner into
~/.douze, whosebinfolder holdsdouze.--previewinstalls the latest preview (there is no stable release yet), and--no-modify-pathskips the shell profile, which a CI job does not read;$GITHUB_PATHadds the folder to thePATHof the next steps. Add--version <version>to pin a version. - Build:
douze -s docsbuilds the site whose source folder isdocs, withdocs/douze.ymlwhen it exists.-ois relative to the current folder, here the repository root, so-o docs/_sitewrites the output next to the sources; without-oorsite.output, it would be./_site. In CI Douze prints one line per step instead of the live view, and exits with 1 when the build has errors, which fails the job. - Deploy:
upload-pages-artifactpacksdocs/_site, anddeploy-pagespublishes it.
For a site at the root of the repository, run douze and upload _site.
Reuse the cache between buildsLink to this heading
Each build of the workflow above starts from scratch. To build only what changed, restore the
disk cache, docs/.douze, which also holds the tools Douze downloads (Pagefind, the language
servers of the hover steps). Add this step before the build:
- name: Restore the cache
uses: actions/cache@v6
with:
path: docs/.douze
key: douze-${{ github.sha }}
restore-keys: douze-
The key changes with every commit, so each build saves a new cache, and restore-keys restores the latest one.
A fresh checkout gives every file the time of the checkout. Only what reads page.date, the modification time, runs
again for that: the pages that show it, and the collections, which sort pages without a front matter date by it. A
site that shows or sorts by page.date gets the right dates, and keeps them stable from one build to the next, by
setting each file's time to its last commit with the script of Add last modified time, which needs
the history:
- uses: actions/checkout@v7
with:
fetch-depth: 0
# ...
- name: Set page dates from Git
run: ./scripts/git-mtime.sh
The script lists the files of _content; for the site of docs, change it to the content folder, such as
docs/_content.
Sites served under a pathLink to this heading
A project site is served under the repository's name: https://<user>.github.io/<repository>/. Root-relative links
(/guide/) then miss the /<repository> prefix. Douze does not rewrite links for a base path, but the output path of
a page follows its folder, so the simplest fix is to put the pages in a folder named after the repository:
docs/
douze.yml
_content/
my-site/
index.md
guide.md
_content/my-site/guide.md is written to docs/_site/my-site/guide/index.html, its url starts with /my-site/, and
so do the links that Douze makes from .md links between pages ([Guide](guide.md) is /my-site/guide/). Upload the
folder of the repository:
- uses: actions/upload-pages-artifact@v5
with:
path: docs/_site/my-site
douze serve -s docs then serves the site at http://localhost:8080/my-site/, as GitHub Pages does. This
documentation site is built this way.
Links written by hand in layouts can also use relative_url, which adds the path of site.url:
site:
url: https://octocat.github.io/my-site
<link href="{{ '/assets/site.css' | relative_url }}" rel="stylesheet">
<link href="/my-site/assets/site.css" rel="stylesheet">
relative_url does not apply to Markdown links, nor to the links Douze makes from .md links: with this approach,
write Markdown links as relative URLs (../guide/) rather than links to .md files.
Other deployment targetsLink to this heading
The same steps work on any CI that runs Linux, macOS or Windows: install Douze (install.ps1 on Windows), build, and
upload the output folder. The script needs curl or wget, and unzip, bsdtar or python3; the GitHub runners
have them. To build in a container, see Build your site with Docker.