mkdocs-source-links 0.3.12

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

Advanced options

plugins:
  - source-links:
      pin: commit             # embed HEAD SHA instead of branch name
      forge: gitlab           # override autodetection for custom domains
      warn_on_missing: false  # silence missing-target warnings
      enabled: !ENV [SOURCE_LINKS, true]  # disable per environment

Line fragments in links (#L10, #L10-L20) are translated to each forge's line-reference syntax. See the configuration docs for all options.

Link conventions and branch resolution

Parent-directory links (../path) to repo files and directories are rewritten to forge blob/tree URLs; links between pages inside docs/ are unchanged. Branch names are resolved from plugin config, extra.git_branch, or edit_uri.

See Usage and Configuration in the docs for the full tables and resolution order.

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 (signed 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