Zum Inhalt

COTRIS Documentation Template

This repository is a template for documentation with optional integrated API documentation. It uses Material for MkDocs and integrates Redoc for API Documentation.

Getting started

  1. Click on 'Use this template' on the top right. Only include the main branch.
  2. Configure mkdocs.yml.
  3. Write your documentation inside /docs and edit the page tree (mkdocs.yml).
  4. Optionally add an openAPI specification file to /docs and refer to it in mkdocs.yml.
  5. Start local development with ./manage.sh dev.
File Structure
.
├─ docs/                 # root of your documentation
│  ├─ index.md
│  └─ petstore.yml
└─ mkdocs.yml            # MkDocs config file
mkdocs.yml
nav:
  - Docs: index.md
  - API: redoc:petstore.yml
  # - Title: redoc:path_to_open_api_spec.yml
  # with /docs as root dictionary

Branch Conventions

You should rename the default main branch to production.

  • dev - development branch for ongoing work
  • next - staging branch for upcoming releases
  • production - main branch for stable, released documentation

Later you should not rename branches easily if you use GitHub variables, because they refer to the branch name.

Deployment

After setting up initially it will update automatically on every new release on GitHub. GitHub CI/CD will build the Container and publish it to the GitHub container registry. Watchtower checks periodically for updates and will pull and restart the container.

Requirements

  • Docker

  • Traefik

    • with docker network proxy
    • for basic example see traefik/ (replace at least the email for letsencrypt in traefik.yaml)

  • Watchtower for automatic updates

    • checks every 5 minutes for updates on the GitHub container registry
    • for basic example see watchtower/

Setup

  1. Set up authentification for GitHub container registry if the package is private

    • get PAT: GitHub > Settings Developer Setting > Personal access tokens > Tokens (classic) > Generate new token with read:packages permissions
    • run docker login ghcr.io -u YOUR_GITHUB_USERNAME -p YOUR_GITHUB_PAT

  2. Copy deploy.compose.yaml

  3. Create and config .env (see: .env.example)

    Image tag

    You should use the branch name as image tag. If you use latest it will update regardles of the branche the release is on.

  4. docker compose -f deploy.compose.yaml up -d

Release a new version

To release a new version use ./manage.sh release script and follow the instructions there.

Release Title

Versioning should follow Semantic versioning.

The productive branch should be named production (preferred) or main.

Productive releases will be:

  • on a productive branch (production)
  • not suffixed (v0.9.5)
  • tagged with Latest

And non-productive releses should be:

  • suffixed with the branch name (v0.8.7-dev)
  • tagged with Pre-release

The Descrption is auto generated.

Do it manually:

Manually you would go to GitHub > Releases and Draft a new release. Then choose your desired branch and the new version as tag and title and publish the Release.

  • Versioning should follow Semantic versioning
  • and Releases should be Set as a pre-release when publishing a non-productive
  • and Set as the latest release on a productive release.

The release will trigger a GitHub workflow which builds and published a container to the GitHub registry. Then Watchtower will dedect the new version and publishes it.

Update Template

If you use this as a template and there is a newer version, you can update your repository with ./manage.sh update.

Do it manually:

  1. Stash all local changes git stash push -m "update-in-progress"

  2. Add the template repository git remote add template https://github.com/cotris/documentation-template

  3. Fetch changes git fetch template

  4. Merge changes git merge --squash template/main --allow-unrelated-histories

  5. Resolve any conflicts

  6. Commit git commit -m "Update from template"

  7. Remove git remote remove template

  8. Pop any stash git stash pop

Features

Basically you can use every feature from Material for MkDocs and Redoc, such as:

  • Built in Search
  • Code blocks
  • Annotations
  • Extra JS/CSS
  • ...

Please refer to thier for further Documentation.

There are also some additional features:

Linking

Of course, you can manually look up the link and then just copy it, but there is also a way to refer to the Documentation or an API Documentation.

To the Docs

You can refer to a page or a specific heading.

  • [WARNING: Link not valid!](/None)
  • [WARNING: Link not valid!](/None#anchor)

title - the page title you specified in the mkdocs.yml
anchor - the anchor slug or plain heading

Example:

[Docs](/) will be replaced to [Docs](/) and then to Docs by markdown.

[Docs - To the API Docs](/#to-the-api-docs)
→ [Docs - To the API Docs](/#to-the-api-docs)
→ Docs - To the API Docs

To the API Docs

You can refer to an API Docs in general, a tag or operation.

  • [Label](redoc::title)
  • [Label](redoc::title::tag)
  • [Label](redoc::title::tag::operationId)

title - the title you specified in the mkdocs.yml
tag - tag of the operation in the openAPI specification
operationId - operationId in the openAPI specification

If you want to link to a tag or operation you have to define it in your openAPI specification.

Example:

[Everything about your Pets](redoc::API) will be replaced to [Everything about your Pets](/petstore/) and then to Everything about your Pets by markdown.

[Access to Petstore orders](redoc::API - Redoc::store)
→ [Access to Petstore orders](/petstore/#tag/store)
→ Access to Petstore orders

[Returns pet inventories by status](redoc::API - Redoc::store::getInventory)
→ [Returns pet inventories by status](/petstore/#tag/store/operation/getInventory)
→ Returns pet inventories by status

GitHub Varibles

GitHub varibels with a defined structure will be passed through to be available as enviorement variables inside the container and then to use in Markdown with Macros. Varibels can be set as Organization, Repository or Environment variables.

GitHub varibles naming convention: DOC__{varible name}__{branch} or COTRIS__{varible name}__{branch}

GitHub varible mkdocs.yml Markdown
DOC__TEST_URL__PRODUCTION !ENV [TEST_URL, "https://default.docs.url"] {{ github_vars.TEST_URL }}
COTRIS__HOMEPAGE_URL__PRODUCTION !ENV [HOMEPAGE_URL] {{ github_vars.HOMEPAGE_URL }}

Here is a full list of all variables passed from the workflow on the last build (16.09.2025 at 11:54 UTC+2):

  • APP_USER_URL: https://docs.cotris.com/app-user/
  • DELIVERY_NOTE_BASIC_URL: https://docs.cotris.com/delivery-note-basic/
  • DELIVERY_NOTE_PRO_URL: https://docs.cotris.com/delivery-note-pro/
  • DIGITAL_DOCUMENT_URL: https://docs.cotris.com/digital-document/
  • STARTING_PAGE_URL: https://docs.cotris.com
  • TOURMANAGEMENT_URL: https://docs.cotris.com/tourmanagement/
  • HOMEPAGE_URL: https://www.cotris.com
  • SUPPORT_URL: https://www.cotris.com/support/
  • REPOSITORY_URL: https://github.com/cotris/documentation-template
  • REPOSITORY_NAME: cotris/documentation-template
  • RELEASE_BRANCH: documentation
  • EDIT_URI: edit/documentation/docs/
  • REPOSITORY_DESCRIPTION: "A Template for Documentations from COTRIS."

Defaults

REPOSITORY_URL, REPOSITORY_NAME, RELEASE_BRANCH, EDIT_URI and REPOSITORY_DESCRIPTION will be set automatically per release.

Prefix

The documentation branch will use the __PRODOCTION suffix.

Local Development

For local development just create a .env file with the variables without prefix and branch:

.env
TEST_URL=example.com
SUPPORT_URL=example.com/support

Layout

.
├─ .cache
├─ .tmp
├─ docs/                            # Documentation root
│  └─ assets/
│  │  ├─ css/
│  │  │   └─ extra.css              # Additional css
│  │  ├─ images/
│  │  └─ js/
│  │      └─ extra.js               # Additional js
│  ├─ index.md
│  └─ petstore.yml                  # OpenAPI Specification
├─ mkdocs-redoc-plugin              # MkDocs Redoc Plugin
├─ mkdocs.yml                       # MkDocs Config
└─ redocly.yaml                     # Redoc Config

Develop this template

Development is done in the documentation branch.

New Release

  1. Merge documentation branch to main. Make shure that main stays a minimal template.
  2. Make a new documentation release like v0.7.5-docs
  3. Make a new main release like v0.7.5

Collaboration

You are welcome to open an issue, request features or just fork and make a pull request :)

Built with Material for MkDocs