GitHub Pages

GitHub Pages is a great way to publish your documentation, especially if you are using GitHub for source control.

Prerequisites

To publish your site to GitHub Pages you will need:

• A GitHub account

Deploying to GitHub Pages

Use the GitHub Actions Workflow.

You might need to configure the basePath in your zudoku.config.ts depending on how your site is hosted. For instance, if your site is available at username.github.io/your-repo/ you would set the basePath to /your-repo.

Code
import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  basePath: "/your-repo",
  //...
};

When basePath is set, Zudoku writes the site into dist/<basePath>/. Upload that nested directory as your Pages artifact, not dist/ itself. For example in a GitHub Actions workflow:

Code
- uses: actions/upload-pages-artifact@v3
  with:
    path: dist/your-repo

Uploading the outer dist/ would nest the site under /your-repo/your-repo/ and every asset would 404.

Accurate Last Modified Dates

If you have enabled the showLastModified option, Zudoku automatically tracks the last modified date of your documentation pages using Git history. However, GitHub Actions performs shallow clones by default, which can result in inaccurate "Last Modified" dates for pages that haven't been updated recently.

To ensure accurate last modified dates, configure the actions/checkout step to fetch the full history:

Code
- uses: actions/checkout@v4
  with:
    fetch-depth: 0 # Fetch all history for all branches and tags

For more details, see the actions/checkout documentation.