Skip to content

MkDocs Source Links

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

MkDocs plugin that rewrites ](../path) links to your git forge in built HTML only. Your source markdown 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/<branch>/<path>
  • Directories -> https://.../tree/<branch>/<path>

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 only parent-directory links in built HTML, leaving your markdown unchanged. You keep IDE- and GitHub-friendly source links; site visitors get working forge URLs.

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 and Configuration for options.

Get involved