Skip to content

ADR 0001: Exclude Pygments 2.20 from Docs Dependencies

Status

Accepted

Date

2026-05-12

Context

GraphForge builds its documentation with MkDocs Material and several pymdownx extensions. The docs dependency group intentionally constrained Pygments to <2.20 because Pygments 2.20.0 changes highlighting behavior in a way that breaks pymdownx handling when title=None is passed through the highlighting path.

Dependabot opened PR #546 to widen the docs dependency from pygments>=2.15,<2.20 to pygments>=2.15,<2.21. The checked-in lockfile still resolved Pygments 2.19.2, so CI stayed green without actually testing Pygments 2.20.0 in the docs environment.

Decision

Keep excluding Pygments 2.20.x from GraphForge's docs dependency group until the upstream compatibility issue with pymdownx is fixed and the docs build has been validated against the newer Pygments release.

Do not merge automated dependency updates that relax the Pygments upper bound to include 2.20.x while the compatibility note remains in pyproject.toml.

Consequences

  • Dependabot PRs that only permit Pygments 2.20.x should be closed rather than merged.
  • The docs environment remains on Pygments 2.19.x through the existing constraint and lockfile.
  • The Pygments 2.20.0 Lua lexer ReDoS fix is not relevant to GraphForge's runtime, because Pygments is only used for documentation tooling.
  • The decision can be revisited once pymdownx and the MkDocs docs build work cleanly with Pygments 2.20.x or newer.

Validation Before Revisiting

Before relaxing the upper bound:

  1. Update the docs dependency group and lockfile so the docs environment resolves the candidate Pygments version.
  2. Confirm the active docs environment imports that candidate version.
  3. Run uv run --group docs mkdocs build --strict.
  4. Remove or update the compatibility note in pyproject.toml.
  • Issue #547: docs: record Pygments 2.20 exclusion decision
  • PR #546: chore(deps-dev): update pygments requirement from <2.20,>=2.15 to >=2.15,<2.21