Skip to content

MkDocs Source Links

OpenSSF Best Practices OpenSSF Baseline OpenSSF Scorecard SLSA 3 PyPI License: MIT CI python

MkDocs plugin that rewrites [text](../path) inline links and [ref]: ../path reference definitions to your git forge during on_page_markdown. Your source markdown on disk keeps relative paths, so links stay clickable in your IDE and on GitHub while the published site points readers at the right blob/tree URL on your forge.

  • Files -> https://.../blob/<ref>/<path> (GitHub/GitLab; other forges use their own URL shapes)
  • Directories -> https://.../tree/<ref>/<path> where the forge distinguishes files from directories

Use pin to embed a branch name (default), commit SHA (commit), or exact tag at HEAD (tag). On Gitea/Codeberg, tags use /src/tag/…; on Azure DevOps, version=GT….

Why

Documentation often lives in docs/ but links to files outside it (../pyproject.toml, ../src/..., ../scripts/). Relative ../ paths are the right choice in source markdown: they work on GitHub and in editors that resolve repo paths, so you can click through to the real file. They break in a built MkDocs site because those files are not part of the rendered docs tree.

This plugin rewrites those [text](../path) and [ref]: ../path links during on_page_markdown (markdown stage), leaving source files unchanged. Forge URLs appear in the built site output.

This site dogfoods the plugin

These docs are built with source-links enabled. In the source markdown the link below points at ../src/mkdocs_source_links/plugin.py (a relative ../ path), but in this built page its destination is a GitHub URL.

Install

pip install mkdocs-source-links

Quick start

# mkdocs.yml
site_name: My project
repo_url: https://github.com/you/your-repo
edit_uri: edit/main/docs/

plugins:
  - source-links

See Usage for link conventions, Configuration for the options table, and Configuration recipes for worked setups.

Get involved