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 docsMakefile
. - 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¶
- Write in standard Markdown; we also support admonitions, call-outs, and Mermaid diagrams.
- Use relative links between pages:
[Gateway API](../api/index.md)
. - For local images place them under
docs/docs/images/
and reference with
. - 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:
- Always include
index.md
first so the folder has a clean landing URL. - List files in the exact order you want them to appear; anything omitted is still built but won't show in the nav.
- You can nest
.pages
files in deeper folders - rules apply hierarchically. - 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.
The build
target produces a fully-static site (used by CI for docs previews and by GitHub Pages).
π€ Publishing (CI)¶
Docs are tested, but not deployed automatically by GitHub Actions on every push to main
. The workflow runs cd docs && make build
.
Publishing is done manually by repo maintainers with make deploy
which publishes the generated site to GitHub Pages.
π Related reading¶
- Building Locally - how to run the gateway itself