MkDocs Hook¶

mkdocs/hooks/config.py patches the MkDocs site config at build time using environment variables. Every dial that would otherwise be hardcoded in mkdocs.yml becomes injectable, letting the same config file produce correct output across different deployments.

How the hook works¶

MkDocs loads Python files listed under hooks: in mkdocs.yml and calls event handlers defined in them. The on_config handler runs before any page is built. It receives the fully-loaded config object, modifies it in place, and returns it.

No MkDocs plugin is required. No package installation is needed beyond MkDocs itself.

Setting up the hook in a repo¶

The hook file must be local. MkDocs does not support remote hook paths.

For repos other than Ireul: copy mkdocs/hooks/config.py from Ireul into hooks/config.py at your repo root. The scaffold at scaffold/new-repo/ includes the correct mkdocs.yml reference.

For Ireul itself: mkdocs.yml points directly at the source file:

# Reference the hook from its canonical source location; other repos copy this file to hooks/config.py
hooks:
  - mkdocs/hooks/config.py

Environment variable reference¶

All variables are optional. If unset, the value in mkdocs.yml is used as-is.

Variable	Overrides	Description
`DOCS_CSS_URL`	`extra_css[0]`	URL of the platform stylesheet; injected as the first CSS entry
`DOCS_SITE_NAME`	`site_name`	Display name shown in the header and browser tab
`DOCS_SITE_URL`	`site_url`	Canonical URL of the deployed site
`DOCS_REPO_URL`	`repo_url`	Repository link shown in the top-right of the site
`DOCS_EDIT_URI`	`edit_uri`	Path appended to `repo_url` for edit-page links
`DOCS_THEME_PRIMARY`	`theme.palette[0].primary`	Material primary colour
`DOCS_THEME_ACCENT`	`theme.palette[0].accent`	Material accent colour
`DOCS_LOGO_PATH`	`theme.logo`	Path or URL to the site logo
`DOCS_ANALYTICS_ID`	`extra.analytics.property`	Google Analytics measurement ID; skipped if unset

Usage examples¶

Local development¶

# Serve docs locally using only mkdocs.yml defaults; no environment variables required for development
mkdocs serve

CI/CD build with full injection¶

# Build and deploy docs with all identity and stylesheet values injected from CI environment variables
DOCS_CSS_URL=https://ireul.pages.dev/platform.css \
DOCS_SITE_NAME="melchior" \
DOCS_SITE_URL=https://melchior.pages.dev \
DOCS_REPO_URL=https://github.com/rtsko/melchior \
DOCS_EDIT_URI=edit/main/docs/ \
mkdocs build

Jenkins pipeline step¶

// Build MkDocs site with platform stylesheet and repo identity injected from pipeline environment variables
withEnv([
    "DOCS_CSS_URL=${env.DOCS_CSS_URL}",
    "DOCS_SITE_NAME=${env.JOB_NAME.split('/')[0]}",
    "DOCS_REPO_URL=https://github.com/rtsko/${env.JOB_NAME.split('/')[0]}"
]) {
    sh 'mkdocs build'
}

Platform stylesheet¶

mkdocs/stylesheets/platform.css is deployed to Cloudflare Pages alongside the Ireul docs site. Its URL is the value of DOCS_CSS_URL in all application repos.

The stylesheet must not be copied into application repos. It is fetched by URL at browser load time. Deploying a new version of the CSS takes effect in all sites immediately without any repo changes.