MkDocs Source Links

Justification: Only the latest release receives fixes (documented in SUPPORT.md and SECURITY.md). Upgrading is the standard PyPI path (pip install -U mkdocs-source-links). Breaking changes are called out in CHANGELOG with semver versioning.
URLs:

• Support scope (latest only): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SUPPORT.md
• Supported versions for security: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#supported-versions
• Changelog / upgrade notes: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/CHANGELOG.md

URL: https://github.com/filipchristiansen/mkdocs-source-links/issues
Justification: GitHub Issues tracks individual bugs and feature requests with labels, search, and permalinks.

Justification: No publicly resolved vulnerability reports in the last 12 months. The project has a private reporting channel (GitHub Security Advisories) and would credit reporters in CHANGELOG/advisory text unless anonymity is requested.
URLs:

• Private reporting: https://github.com/filipchristiansen/mkdocs-source-links/security/advisories/new
• Security policy: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#reporting-a-vulnerability

Justification: SECURITY.md is the coordinated disclosure policy: private GitHub Security Advisories channel, supported versions (latest release only), 14-day initial response SLA, and explicit instruction not to file public issues for security problems.
URLs:

• SECURITY.md: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md
• GitHub security policy UI: https://github.com/filipchristiansen/mkdocs-source-links/security/policy

Justification: CONTRIBUTING.md identifies ruff (formatting + lint), mypy (types), pylint, pydoclint (docstrings), markdownlint, taplo, and ShellCheck for scripts. NumPy-style docstrings are required for public APIs.
URLs:

• Coding standards: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/CONTRIBUTING.md#coding-standards
• Ruff/mypy/coverage config: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml
• Pre-commit hooks: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.pre-commit-config.yaml

Justification: Pre-commit runs ruff, mypy, pylint, pydoclint, markdownlint, taplo, and ShellCheck. CI lint job runs the same hooks on every PR/push to main via uv sync --frozen + pre-commit. Style exceptions are limited to documented per-file ruff ignores in pyproject.toml.
URLs:

• CI lint job: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/ci.yml
• Pre-commit config: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.pre-commit-config.yaml
• Makefile (make lint / make ci): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/Makefile

Justification: The project produces no native binaries (C/C++/Rust). It is a Python package built with uv build (pure Python wheel/sdist).
URLs:

• Package build (Python only): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/publish.yml

Justification: No native compilation or install -s stripping step. Python source is shipped as-is in sdist; wheels contain bytecode only.

Justification: No recursive native build system. Single Python package under src/ with flat module layout.

Justification: Runtime is interpreted Python (no bit-for-bit native artifact compilation). Release reproducibility is supported via pinned uv.lock, uv sync --frozen in CI/publish, and SLSA Level 3 provenance on release artifacts.
URLs:

• Lockfile: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/uv.lock
• SLSA provenance on releases: https://filipchristiansen.github.io/mkdocs-source-links/security/#verify-integrity-and-authenticity

Justification: End users install via PyPI (pip install mkdocs-source-links / uv add). Uninstall via pip uninstall mkdocs-source-links. This follows the standard Python packaging convention.
URLs:

• PyPI package: https://pypi.org/project/mkdocs-source-links/
• README install: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/README.md#install

Justification: Installation is delegated to pip/uv into the active Python environment. The project does not implement its own POSIX installer; pip honors standard site-packages conventions and virtualenv isolation.
URLs:

• pyproject.toml packaging metadata: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml

Justification: CONTRIBUTING.md documents one-command dev setup (make install) using uv + pre-commit. Full verification via make ci (lint, audit, tests at 100% coverage, strict docs build). Python version and dependency groups are declared in pyproject.toml.
URLs:

• Development setup: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/CONTRIBUTING.md#development-setup
• Makefile targets: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/Makefile
• Python requirement: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml

Justification: Runtime deps in [project]; dev/docs groups in [dependency-groups]; full graph pinned in uv.lock. CI and publish use uv sync --frozen.
URLs:

• pyproject.toml: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml
• uv.lock: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/uv.lock
• CI frozen sync: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/ci.yml

Justification: pip-audit runs in a dedicated CI job on every PR/push to main. Dependabot opens weekly PRs for uv.lock and GitHub Actions. Critical/High CVEs block merge/release per SECURITY.md.
URLs:

• CI audit job: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/ci.yml
• make audit: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/Makefile
• Remediation policy: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#dependency-vulnerability-policy
• Dependabot config: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/dependabot.yml

Justification: Direct runtime dependency (MkDocs) is declared in pyproject.toml; transitive deps are pinned in uv.lock and updated via Dependabot lockfile PRs. No vendored copies of third-party code.
URLs:

• Direct dependencies: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml
• Lockfile: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/uv.lock
• Dependabot: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/dependabot.yml

Justification: The codebase uses current MkDocs plugin hooks and standard library APIs. No deprecated/obsolete API usage is known; CI runs on Python 3.10–3.13 and current MkDocs 1.5+.
URLs:

• CI Python matrix: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/ci.yml
• Runtime requirement (MkDocs >=1.5): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml

Justification: pytest suite (unit + integration) runs in CI on every PR and push to main across Python 3.10–3.13 plus Windows/macOS smoke jobs. Docs build runs in a separate workflow on the same triggers. Results reported in GitHub Actions.
URLs:

• CI workflow: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/ci.yml
• Docs CI: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/docs.yml
• Integration tests: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/tests/test_integration.py
• CI history: https://github.com/filipchristiansen/mkdocs-source-links/actions

Justification: Six user-visible bugs fixed in the last six months (0.3.1 angle-bracket links; 0.3.2 Gitea commit URLs, forge autodetection, .git suffix stripping, _view_ref init, GitLab edit_uri parsing; earlier fenced-code and no-backing-file fixes) each have corresponding pytest regression tests — well above the 50% threshold.
URLs:

• Changelog fixes: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/CHANGELOG.md
• Example regression tests: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/tests/test_rewrite.py
• Plugin edge-case tests: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/tests/test_plugin.py

Justification: pytest-cov enforces 100% statement coverage (fail_under = 100 in pyproject.toml). CI runs coverage on Ubuntu/Python 3.10; local make test/make ci use the same gate. Current suite: 145 tests, 100% coverage.
URLs:

• Coverage config: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml
• CI coverage step: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/ci.yml
• Codecov: https://codecov.io/gh/filipchristiansen/mkdocs-source-links

Justification: CONTRIBUTING.md step 2 requires tests for every change and mandates 100% coverage. PR template includes a test-plan checklist. Coverage gate in pyproject.toml enforces the policy automatically.
URLs:

• CONTRIBUTING.md workflow: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/CONTRIBUTING.md#workflow
• PR template: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/pull_request_template.md
• Coverage gate: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml

URLs:

• Change proposal instructions (CONTRIBUTING.md): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/CONTRIBUTING.md
• PR template test plan: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/pull_request_template.md
  Justification: Documented in CONTRIBUTING.md step 2 ("Make your change and add tests. The suite must stay at 100% coverage.") and reinforced by the PR template test plan checklist.

URLs:

• Ruff strict rules + bandit S-rules: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml
• Pre-commit / mypy / pylint: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.pre-commit-config.yaml
• CodeQL analysis: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/codeql.yml

Justification: SECURITY.md documents secure-design choices for this build-time plugin: fail-safe defaults (leave links unchanged on missing targets/ambiguous forge), complete mediation (path normalization with relative_to repo root; skip code blocks), least privilege in CI (read-only permissions; OIDC PyPI publish), and minimal runtime attack surface (no network, no code execution of user input).
URLs:

• Security assessment: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• Path handling (rewrite.py): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/src/mkdocs_source_links/rewrite.py
• CI/CD hardening: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#cicd-hardening

Justification: mkdocs-source-links is a build-time MkDocs plugin. It does not implement or use cryptographic protocols, algorithms, keys, password storage, TLS, or RNG. It reads local files and git metadata and emits rewritten markdown URLs.
URLs:

• Scope statement: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• README: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/README.md

Justification: mkdocs-source-links is a build-time MkDocs plugin. It does not implement or use cryptographic protocols, algorithms, keys, password storage, TLS, or RNG. It reads local files and git metadata and emits rewritten markdown URLs.
URLs:

• Scope statement: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• README: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/README.md

Justification: mkdocs-source-links is a build-time MkDocs plugin. It does not implement or use cryptographic protocols, algorithms, keys, password storage, TLS, or RNG. It reads local files and git metadata and emits rewritten markdown URLs.
URLs:

• Scope statement: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• README: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/README.md

Justification: mkdocs-source-links is a build-time MkDocs plugin. It does not implement or use cryptographic protocols, algorithms, keys, password storage, TLS, or RNG. It reads local files and git metadata and emits rewritten markdown URLs.
URLs:

• Scope statement: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• README: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/README.md

Justification: mkdocs-source-links is a build-time MkDocs plugin. It does not implement or use cryptographic protocols, algorithms, keys, password storage, TLS, or RNG. It reads local files and git metadata and emits rewritten markdown URLs.
URLs:

• Scope statement: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• README: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/README.md

Justification: mkdocs-source-links is a build-time MkDocs plugin. It does not implement or use cryptographic protocols, algorithms, keys, password storage, TLS, or RNG. It reads local files and git metadata and emits rewritten markdown URLs.
URLs:

• Scope statement: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• README: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/README.md

Justification: mkdocs-source-links is a build-time MkDocs plugin. It does not implement or use cryptographic protocols, algorithms, keys, password storage, TLS, or RNG. It reads local files and git metadata and emits rewritten markdown URLs.
URLs:

• Scope statement: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• README: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/README.md

Justification: Releases intended for widespread use (PyPI + GitHub Releases) are tied to GitHub-verified signed annotated tags (git tag -s), enforced by verify-release-tag.sh before publish. SLSA Level 3 provenance (.intoto.jsonl) provides cryptographic attestation of build integrity. docs/security.md documents how consumers verify tag signatures (public keys on GitHub) and provenance with slsa-verifier. Signing private keys are held locally by the maintainer, not on distribution sites.
URLs:

• Consumer verification guide: https://filipchristiansen.github.io/mkdocs-source-links/security/
• Tag verification script: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/scripts/verify-release-tag.sh
• Publish workflow: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/publish.yml
• Signed-tag policy: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/CONTRIBUTING.md#signed-tags-and-commits

Justification: Every release tag vX.Y.Z is a signed annotated tag verified by GitHub before PyPI upload. Release automation uses git tag -s; unsigned/unverified tags are rejected in CI.
URLs:

• Release tagging (git tag -s): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/scripts/release.py
• Tag verification gate: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/scripts/verify-release-tag.sh
• Verify author identity (consumer docs): https://filipchristiansen.github.io/mkdocs-source-links/security/#verify-release-author-identity

Justification: Untrusted inputs (markdown links, mkdocs.yml config, repo paths) are validated defensively: only ../ parent links are rewritten; paths are resolved and constrained to the repo root via Path.relative_to; fenced/inline code is skipped; forge hosts are allowlisted; MkDocs config options use typed schemas (bool, Choice enums); URLs are built with urllib.parse.quote.
URLs:

• Path allowlisting: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/src/mkdocs_source_links/rewrite.py
• Config schema: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/src/mkdocs_source_links/plugin.py
• Forge allowlist: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/src/mkdocs_source_links/urls.py
• Tests: https://github.com/filipchristiansen/mkdocs-source-links/tree/main/tests

Justification: Hardening appropriate to a build-time Python plugin: path traversal prevention, strict static analysis (ruff bandit S-rules, mypy, pylint, CodeQL), dependency auditing (pip-audit), least-privilege GitHub Actions permissions, required PR review, signed commits on main, and SLSA provenance on releases.
URLs:

• Threat mitigations table: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#likely-threats-and-mitigations
• CodeQL workflow: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/codeql.yml
• CI audit: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/ci.yml

Justification: SECURITY.md § Security assessment is the assurance case: threat model (path bugs, URL generation, supply chain, malicious contributions), trust boundaries (author, MkDocs, plugin, forge), secure-design arguments (fail-safe defaults, path mediation, no runtime network), and countermeasures for common weaknesses (review, SAST, lockfile, signed tags, SLSA). Residual risks are documented explicitly.
URLs:

• Assurance case / threat model: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#security-assessment
• Residual risks: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/SECURITY.md#residual-risks
• Consumer verification: https://filipchristiansen.github.io/mkdocs-source-links/security/

Justification: Static analysis for common Python vulnerabilities runs on every change and in scheduled CI. Ruff enables flake8-bandit rules (rule set "S") in pyproject.toml for issues such as unsafe subprocess use and hardcoded secrets. pylint adds further checks via pre-commit and the CI lint job. CodeQL analyzes Python on pull requests, pushes to main, and a weekly schedule; SARIF is uploaded to GitHub code scanning.
URLs:

• Ruff bandit rules (pyproject.toml): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/pyproject.toml
• Pre-commit / lint (ruff, pylint): https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.pre-commit-config.yaml
• CI lint job: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/ci.yml
• CodeQL workflow: https://github.com/filipchristiansen/mkdocs-source-links/blob/main/.github/workflows/codeql.yml
• Code scanning (SARIF): https://github.com/filipchristiansen/mkdocs-source-links/security/code-scanning

The project is implemented entirely in Python. No C, C++, or other memory-unsafe language code is produced by this project.