mkdocs-external-code

A MkDocs plugin: the @code: directive fetches a file's raw content from a GitHub repository (via the GitHub API) at build/serve time and renders it as a syntax-highlighted code block — so docs reference the real source instead of maintaining a copy.

Install

Requires Python 3.12–3.15.

pip install mkdocs-external-code

Configure

plugins:
  - external-code:
      org: my-org          # required: GitHub org whose repos may be referenced
      default_ref: main    # optional, default "main"
      token_env: GH_READ_TOKEN  # optional, default "GH_READ_TOKEN"

Usage

@code:bash my-org/my-repo/tools/deploy.sh
@code:yaml my-org/my-repo@a1b2c3d/values.yaml   # pin a ref with @<sha>
@code:my-org/my-repo/app.py                     # language omitted -> inferred

Rules:

• Only the configured org is allowed; other orgs fail the build with a clear error.
• The language name after @code: is optional — it is inferred from the file extension (.sh → bash, .hcl → hcl, .py → python, Dockerfile → dockerfile, ...) and defaults to text. Omitting the language needs no space: @code:my-org/... and @code: my-org/... both work.
• @ref is optional: omitted uses default_ref (or the EXTERNAL_DEFAULT_REF env var if set). Pin an exact version with @<commit-sha> (refs containing / are not supported).
• The generated block inherits the directive's indentation and is padded with blank lines, so a directive may be nested in a list item or an admonition. Indented fences need pymdownx.superfences; without it the plugin emits the block at column 0 (still a code block, but outside the container).
• Directives inside code fences or inline code are ignored (so you can document the syntax in a fenced block without executing it).

Access to private repos

The plugin reads the token for token_env in this order:

1. the environment variable (or a .env file — the plugin loads it itself; the directory of your mkdocs.yml is checked first, then the current working directory, and existing variables are never overridden);
2. if unset, requests are anonymous (public repos only).

A GitHub Personal Access Token (prefer fine-grained) with Contents: Read on each referenced repo is enough. In GitHub Actions, inject it explicitly:

- run: mkdocs build
  env:
    GH_READ_TOKEN: ${{ secrets.REPO_READ_PAT }}

Note: the default GITHUB_TOKEN only covers the repository running the workflow; it cannot read other private repos.

Limitations

• Only UTF-8 text files are supported — binary or non-UTF-8 content fails the build with a clear error.
• Files are fetched through the GitHub Contents API, which caps file size at 1 MB; larger files fail with a clear error (use a raw.githubusercontent.com URL form if you need them).
• Anonymous requests are rate-limited by GitHub (60/hour per IP); pass a token to raise the limit.
• Fetched content is cached for the process lifetime — during mkdocs serve, restart the server to pick up changed remote content.
• @ref must not contain / (e.g. branch names like feature/x); pin a commit SHA instead.
• Fenced code blocks and inline code are detected; indented (4-space) code blocks are not — use a fenced block to show the directive syntax literally.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e .
python -m unittest discover -s tests -v
ruff check . && ruff format --check .

Releasing

Pushing a v* tag publishes that tag to PyPI automatically. The Release workflow can also be run manually (workflow_dispatch) to publish an existing tag again.

1. Bump the version in pyproject.toml and mkdocs_external_code/__init__.py, commit and push.
2. Create and push the tag: git tag -a v0.1.2 -m v0.1.2 && git push origin v0.1.2. This triggers the release; the workflow checks that the tag matches the package version, builds the sdist/wheel and publishes to PyPI via trusted publishing.
3. Manual fallback: GitHub → Actions → Release → Run workflow, enter the tag (e.g. v0.1.2) or leave it empty for the latest v* tag.
4. One-time PyPI setup: add a trusted publisher (pending publisher while the project does not exist yet) with owner calmzhu, repository mkdocs-external-code, workflow release.yml and no environment name — no API token secret is required.

License

MIT