Publish on GitHub Pages

Put the knowledge base at the root of a GitHub repository, or in a folder of an existing one:

config/repo.json
source/...

Do not commit the generated files. Add a .gitignore next to config/:

var/
target/

Keep "source": "source" and "target": "target" in repo.json. They are relative to the knowledge base folder, so the build works on any computer. kb4it create writes them that way.

Create .github/workflows/site.yml:

name: site

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-python@v7
        with:
          python-version: '3.12'
      - run: pip install KB4IT
      - run: kb4it build config/repo.json
      - uses: actions/upload-pages-artifact@v5
        with:
          path: target

  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

If the knowledge base is in a folder, say docs-site/, use docs-site/config/repo.json and path: docs-site/target.

In the repository on GitHub, open Settings, then Pages, and under Build and deployment set Source to GitHub Actions. Or from a terminal with the GitHub CLI:

gh api -X POST repos/OWNER/REPO/pages -f build_type=workflow

Push a change. The site appears at https://OWNER.github.io/REPO/. The Actions tab shows each build and its log.

Add kb4it verify config/repo.json before the build step to stop the publish when a document cannot be read, or set "fail_on_invalid": true in repo.json.

This help is published exactly this way; see .github/workflows/help.yml in the KB4IT repository.