MkDocs Source Links

MkDocs plugin that rewrites [text](../path) inline links and [ref]: ../path reference definitions to your git forge during on_page_markdown (before HTML is built). Source markdown on disk is unchanged; forge URLs appear in the built site.

• Files → https://…/blob/<ref>/<path> (GitHub/GitLab; forge-specific paths on Gitea, Bitbucket, Azure)
• Directories → https://…/tree/<ref>/<path> where the forge distinguishes files from directories
• Pin ref: pin: branch (default), pin: commit (HEAD SHA), or pin: tag (exact tag at HEAD; Gitea uses /src/tag/…, Azure uses GT…)
• Forges: GitHub, GitLab, Bitbucket Cloud, 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
      # pin: tag              # exact tag at HEAD (release builds); else resolved branch
      forge: gitlab           # override autodetection for custom domains
      warn_on_missing: false  # silence missing-target warnings
      log_rewrites: summary   # or verbose for per-page counts; false by default
      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

Complete inline [text](../path) links and [ref]: ../path definitions targeting repo files and directories are rewritten to forge blob/tree URLs; links between pages inside docs/ are unchanged. Lonely ](../path) suffixes in prose are not matched. 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        # pre-PR checks: lint, audit, test (with coverage), docs build

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 for the full workflow and Changelog for release notes. Further reading: Governance, Roadmap, Support, Code of conduct, Maintainers, Security policy, and Release verification.

License

MIT