Deploy MkDocs to Forgejo Pages

Documentation deploys should be boring: build from the repository and publish the exact generated site.

Pages

What this solves

You want project documentation hosted from the same Forgejo workflow that tests the code.

Best fit

Internal docs
Open-source project docs
Migration from GitHub Pages

How to think about it

MkDocs works best when docs builds are treated like tests. Install the same dependency set every time, make warnings visible, and publish only after the generated site is complete.

MkDocs build job

name: docs
on: [push]

jobs:
  build:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: python -m pip install -r requirements.txt
      - run: mkdocs build --strict
      - run: test -f site/index.html

Practical path

01 Install Python dependencies in the workflow.
02 Run `mkdocs build` and keep warnings visible.
03 Publish the generated site directory and link it from the repository README.

When to choose another path

Use `mkdocs build --strict` so broken links fail before deployment.

Keep docs dependencies pinned for repeatable output.

Publish from the generated `site` directory, not from source markdown.

Next resources

Pages docs

How Fjord Pages deploys static sites.

Actions docs

Workflow basics for deploy jobs.

CLI

Trigger and inspect deploy workflows.

Operations

Run the forge behind the site calmly.