https://github.com/filipchristiansen/mkdocs-source-links
MkDocs plugin that rewrites `[text](../path)` inline links and `[ref]: ../path` definitions to forge view URLs during `on_page_markdown`.
https://github.com/filipchristiansen/mkdocs-source-links
azure-devops bitbucket codeberg documentation documentation-tool forgejo gitea github gitlab links markdown mkdocs mkdocs-material mkdocs-plugin pypi pypi-package python python3 static-site-generator
Last synced: about 6 hours ago
JSON representation
MkDocs plugin that rewrites `[text](../path)` inline links and `[ref]: ../path` definitions to forge view URLs during `on_page_markdown`.
- Host: GitHub
- URL: https://github.com/filipchristiansen/mkdocs-source-links
- Owner: filipchristiansen
- License: mit
- Created: 2026-06-16T15:06:31.000Z (20 days ago)
- Default Branch: main
- Last Pushed: 2026-06-25T07:13:06.000Z (12 days ago)
- Last Synced: 2026-06-25T09:02:26.191Z (11 days ago)
- Topics: azure-devops, bitbucket, codeberg, documentation, documentation-tool, forgejo, gitea, github, gitlab, links, markdown, mkdocs, mkdocs-material, mkdocs-plugin, pypi, pypi-package, python, python3, static-site-generator
- Language: Python
- Homepage: https://filipchristiansen.github.io/mkdocs-source-links/
- Size: 473 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# MkDocs Source Links
[](https://www.bestpractices.dev/projects/13299)
[](https://www.bestpractices.dev/projects/13299)
[](https://scorecard.dev/viewer/?uri=github.com/filipchristiansen/mkdocs-source-links)
[](https://github.com/filipchristiansen/mkdocs-source-links/releases/latest)
[](https://pypi.org/project/mkdocs-source-links)
[](https://github.com/filipchristiansen/mkdocs-source-links/blob/main/LICENSE)
[](https://github.com/filipchristiansen/mkdocs-source-links/actions/workflows/ci.yml?query=branch%3Amain)
[](https://codecov.io/gh/filipchristiansen/mkdocs-source-links)
[](https://www.python.org/downloads)
[](https://docs.astral.sh/uv)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org)
[](https://github.com/pre-commit/pre-commit)
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//` (GitHub/GitLab; forge-specific paths on Gitea, Bitbucket, Azure)
- **Directories** → `https://…/tree//` 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:**
## Install
```bash
pip install mkdocs-source-links
```
## Usage
```yaml
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:
```yaml
plugins:
- source-links:
branch: develop
```
## Advanced options
```yaml
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](https://filipchristiansen.github.io/mkdocs-source-links/configuration/)
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](https://filipchristiansen.github.io/mkdocs-source-links/usage/) and
[Configuration](https://filipchristiansen.github.io/mkdocs-source-links/configuration/) in the docs
for the full tables and resolution order.
## Contributing
This project uses [uv](https://docs.astral.sh/uv), [pre-commit](https://pre-commit.com), and a `Makefile`.
```bash
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](https://filipchristiansen.github.io/mkdocs-source-links/contributing/) for the full workflow and [Changelog](https://filipchristiansen.github.io/mkdocs-source-links/changelog/) for
release notes. Further reading: [Governance](https://filipchristiansen.github.io/mkdocs-source-links/governance/), [Roadmap](https://filipchristiansen.github.io/mkdocs-source-links/roadmap/), [Support](https://filipchristiansen.github.io/mkdocs-source-links/support/), [Code of conduct](https://filipchristiansen.github.io/mkdocs-source-links/code-of-conduct/), [Maintainers](https://github.com/filipchristiansen/mkdocs-source-links/blob/main/MAINTAINERS.md), [Security policy](https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md), and [Release verification](https://filipchristiansen.github.io/mkdocs-source-links/security/).
## License
MIT