Skip to content

Writing & Publishing Documentation

Follow this guide when you need to add or update markdown pages under docs/ and preview the documentation locally.

🧩 Prerequisites

  • Python ≥ 3.11 (only for the initial virtual env - not required if you already have one)
  • make (GNU Make 4+)
  • (First-time only) mkdocs-material and plugins are installed automatically by the docs Makefile.
  • One-time GitHub setup, e.g. gitconfig setup

⚡ One-liner for a live preview

cd docs
make venv     # First-time only, installs dependencies into a venv under `~/.venv/mcpgateway-docs`
make serve    # http://localhost:8000 (auto-reload on save)

The serve target automatically creates a project-local virtual environment (under ~/.venv/mcpgateway-docs) the first time you run it and installs all doc dependencies before starting MkDocs in live-reload mode.

📂 Folder layout

repo-root/
├─ docs/              # MkDocs project (DO NOT put .md files here!)
│  ├─ docs/           # <-- ────────────▶  place Markdown pages here
│  │  └─ ...
│  ├─ mkdocs.yml      # MkDocs config & navigation
│  └─ Makefile        # build / serve / clean targets
└─ Makefile           # repo-wide helper targets (lint, spellcheck, ...)
  • Add new pages inside docs/docs/ - organise them in folders that make sense for navigation.
  • Update navigation: edit .pages for your section so your page shows up in the left-hand nav.

Tip: MkDocs Material auto-generates "Edit this page" links - keep file names lowercase-hyphen-case.

✏️ Editing tips

  1. Write in standard Markdown; we also support admonitions, call-outs, and Mermaid diagrams.
  2. Use relative links between pages: [Configuration](../manage/configuration.md).
  3. For local images place them under docs/docs/images/ and reference with ![](../images/example.png).
  4. Never edit mkdocs.yml - all nav structure is defined in .pages files (one per directory).

✏️ Writing docs

Start each new Markdown file with a clear # Heading 1 title - this becomes the visible page title and is required for proper rendering in MkDocs.

Follow the conventions and layout guidelines from the official MkDocs Material reference for callouts, tables, code blocks, and more. This ensures consistent formatting across the docs.

Keep file names in lowercase-hyphen-case.md and use relative links when referencing other docs or images.

🗂️ Ordering pages with .pages

For directories that contain multiple Markdown files, we rely on the awesome-pages MkDocs plugin.

Creating a .pages file inside a folder lets you:

  • Set the section title (different from the folder name).
  • Control the left-nav order without touching the root mkdocs.yml.
  • Hide specific files from the navigation.

We do not auto-generate the nav: structure - you must create .pages manually.

Example - docs for the development section:

# docs/docs/development/.pages
# This file affects ONLY this folder and its sub-folders

# Optional: override the title shown in the nav
# title: Development Guide

nav:
  - index.md        # ➟ /development/ (landing page)
  - github.md       # contribution workflow
  - building.md     # local build guide
  - packaging.md    # release packaging steps

Guidelines:

  1. Always include index.md first so the folder has a clean landing URL.
  2. List files in the exact order you want them to appear; anything omitted is still built but won't show in the nav.
  3. You can nest .pages files in deeper folders - rules apply hierarchically.
  4. Avoid circular references: do not include files from other directories.

After saving a .pages file, simply refresh the browser running make serve; MkDocs will hot-reload and the navigation tree will update instantly.

✅ Pre-commit checklist

From the repository root run all lint & QA checks before pushing:

make spellcheck           # Spell-check the codebase
make spellcheck-sort      # Sort local spellcheck dictionary
make markdownlint         # Lint Markdown files with markdownlint (requires markdownlint-cli)
make pre-commit           # Run all configured pre-commit hooks

These targets are defined in the top-level Makefile. Make sure you're in the repository root when running these targets.

🧹 Cleaning up

cd docs
make clean       # remove generated site/
make git-clean   # remove ignored files per .gitignore
make git-scrub   # blow away *all* untracked files - use with care!

🔄 Rebuilding the static site

This is not necessary, as this will be done automatically when publishing.

cd docs
make build    # outputs HTML into docs/site/

The build target produces a fully-static site (used by CI for docs previews and by GitHub Pages).

📤 Publishing (CI)

We do not currently run a dedicated docs-build workflow in CI. Build locally with make build (or the make doctest/make lint suite from the repo root) before opening a PR that touches docs-heavy changes.

Publishing to GitHub Pages remains a manual maintainer task via make deploy.