Documentation Workflow¶

The Documentation workflow builds the MkDocs documentation of a project and publishes it to GitHub Pages.

Documentation Setup

To quickly setup documentation in your project, copy the docs/ folder from the mkdocs-material-template project into the /docs/ directory in the root of your repository.

Usage¶

To use the Documentation workflow in your GitHub repository, create a .github/workflows/documentation.yaml file with at minimum the following contents:

.github/workflows/documentation.yaml

---
name: 'Documentation'

on:  # yamllint disable-line rule:truthy
  push:
    branches:
      - main
  workflow_dispatch: {}  # Allow running this workflow manually (Actions tab)

jobs:
  documentation:
    uses: metaborg/actions/.github/workflows/mkdocs-material.yaml@main

Adjust the name of the branches whose dependencies are submitted on push.

Advanced Usage¶

You can adjust several parameters to the workflow:

docs-dir: The subdirectory with the MkDocs documentation.

.github/workflows/documentation.yaml

# ...
jobs:
  documentation:
    uses: metaborg/actions/.github/workflows/mkdocs-material.yaml@main
    with:
      docs-dir: 'docs'

For the default values, see the definition.

Example¶

A good example of a project using this workflow is the Gitonium project. See the Documentation workflow at .github/workflows/documentation.yaml and the results of the workflow on the Actions page.