This repository contains the source code for documentation, built with MkDocs and versioned using mike.

The goal of this README is to help you:

• Make documentation changes safely
• Preview docs locally with minimal friction
• Understand how CI/CD publishes the docs

You will mostly work in two directories only:

• content/ – documentation pages (Markdown)
• theme_override/ – local theme customizations

⚠️ Important

• Do not edit files in dist/ – it is generated
• Do not edit theme_common/ directly unless you know what you are doing
• Only edit theme_override/mkdocs.yml (there are multiple mkdocs files)

This repository is fully automated via GitHub Actions:

• Pull Requests

  • Runs documentation QA checks
  • Builds Docker image
  • Publishes preview docs at:

  https://stakater.github.io/support-docs/<branch-name>/

• Merge to main

  • Creates a GitHub release
  • Builds & pushes documentation image
  • Update the GitOps repository
  • Publishes docs to:

  https://docs.stakater.com

This repository depends on a shared MkDocs theme via a git submodule:

git submodule update --init --recursive

If you forget this step, local builds and Docker builds will fail.

To update the submodule to the latest version:

git submodule update --init --recursive --remote

You can inspect linked submodules in .gitmodules.

You have two supported ways to preview docs locally.

This is the most reliable method and matches CI behavior.

docker build -f DockerfileLocal -t docs-local .

docker run --rm -p 8080:8080 docs-local

Open your browser:

http://localhost:8080

• Python 3.x
• virtualenv or virtualenvwrapper

python3 -m venv .venv
source .venv/bin/activate

This script:

• Installs Python dependencies from theme_common
• Merges shared + local theme overrides
• Generates mkdocs.yml

./prepare_theme.sh

mike serve

or

python3 -m mike serve

Docs will be available at:

http://localhost:8000

💡 Any changes to dist/_theme will be lost. Always move permanent changes to:

• theme_override/
• or content/

1. Fork the repository
2. Create a feature branch
3. Make changes in content/ or theme_override/
4. Open a Pull Request
5. Ensure all CI checks pass
6. Request review

Once merged, the docs are automatically published.

brew install markdownlint-cli
markdownlint -c .markdownlint.yaml content

brew install vale
vale sync
vale content

These checks also run automatically in CI.

If local builds fail:

1. Verify theme_common/requirements.txt exists
2. Ensure submodules are initialized
3. Try the Docker-based build

This will catch 99% of issues.