mkdocs-source-links 0.3.1

MkDocs plugin: rewrite ../ repo links to forge view URLs in built HTML

MkDocs Source Links

MkDocs plugin that rewrites ](../path) links to your git forge in built HTML only. Source markdown keeps relative paths so GitHub and your IDE still work.

• Files → https://…/blob/<branch>/<path>
• Directories → https://…/tree/<branch>/<path>
• Forges: GitHub, GitLab, Bitbucket, Gitea/Forgejo, Azure DevOps (autodetected; self-hosted via forge:)

Documentation: https://filipchristiansen.github.io/mkdocs-source-links

Install

pip install mkdocs-source-links

Usage

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

plugins:
  - source-links

Requires repo_url in mkdocs.yml (shown above). Without it, links are left unchanged.

Optional branch override:

plugins:
  - source-links:
      branch: develop

Link conventions

Target	Source markdown	Built HTML
Page in docs/	[runbook](other.md)	unchanged (MkDocs handles it)
Repo file outside docs/	[config](../backend/config.py)	forge blob URL
Repo directory	[scripts](../scripts/)	forge tree URL

Branch configuration

Branch for forge URLs is resolved in order:

1. Plugin branch: config
2. extra.git_branch in mkdocs.yml
3. Parsed from edit_uri (edit/<branch>/… or blob/<branch>/…)
4. Fallback: main

If your default branch is not main, set edit_uri, extra.git_branch, or source-links.branch.

Contributing

This project uses uv, pre-commit, and a Makefile.

make install   # install Python 3.10, sync all groups, set up pre-commit hooks
make ci        # run the full pre-PR suite: lint, test, coverage

Maintainers release with make release-prep VERSION=X.Y.Z (bump, roll the hand-written CHANGELOG.md, open the release PR) and, once merged, make release-tag VERSION=X.Y.Z (tag and publish to PyPI).

See CONTRIBUTING.md for the full workflow and CHANGELOG.md for release notes. Security issues: see SECURITY.md.

License

MIT