Skip to content

fix: bump pymdown-extensions for pygments 2.20.0 compat#482

Merged
eric-tramel merged 2 commits intomainfrom
fix/bump-pymdown-extensions-for-pygments-compat
Mar 31, 2026
Merged

fix: bump pymdown-extensions for pygments 2.20.0 compat#482
eric-tramel merged 2 commits intomainfrom
fix/bump-pymdown-extensions-for-pygments-compat

Conversation

@eric-tramel
Copy link
Copy Markdown
Contributor

@eric-tramel eric-tramel commented Mar 31, 2026

Summary

Fix to regain capability to run make serve-docs-locally.

  • Pygments 2.20.0 (released 2026-03-29, security fix) introduced stricter handling of filename=None in HtmlFormatter, causing mkdocs build to crash on code reference pages (e.g., code_reference/analysis.md).
  • pymdown-extensions 10.21.2 (also released 2026-03-29) fixes the incompatibility by coercing None to "" before passing to pygments.
  • The lockfile previously pinned pymdown-extensions at 10.21. Since it is a transitive dependency (from mkdocs-material and mkdocstrings), this PR adds an explicit "pymdown-extensions>=10.21.2" lower-bound constraint to the docs dependency group to ensure the fix is always resolved.

@eric-tramel eric-tramel requested a review from a team as a code owner March 31, 2026 17:39
@greptile-apps
Copy link
Copy Markdown
Contributor

greptile-apps Bot commented Mar 31, 2026

Greptile Summary

This PR is a targeted dependency maintenance fix: it adds an explicit pymdown-extensions>=10.21.2,<11 lower-bound to the docs dependency group in pyproject.toml and updates the lockfile accordingly, bumping the resolved version from 10.21 → 10.21.2.

  • The motivation is sound: pygments 2.20.0 introduced stricter filename handling in HtmlFormatter, causing mkdocs build to crash. pymdown-extensions 10.21.2 fixes this by coercing None to "" before the call.
  • Because pymdown-extensions was previously only a transitive dependency (pulled in by mkdocs-material and mkdocstrings), pinning it explicitly in the docs group is the correct approach to guarantee the floor version.
  • The version range >=10.21.2,<11 follows the same major-version-capped pattern used for all other docs dependencies in this file.
  • The lockfile update is consistent: revision bumped, docs group entries updated, and the new PyPI wheel/sdist URLs with correct SHA256 hashes are recorded.

Confidence Score: 5/5

Safe to merge — a well-scoped dependency bump with no logic changes and a consistent lockfile update.

No code logic changes; only a dependency version floor is raised from 10.21 to 10.21.2 and the lockfile is updated accordingly. The constraint follows established conventions in the file, the upper bound is properly set, and the PR description clearly justifies the change.

No files require special attention.

Important Files Changed

Filename Overview
pyproject.toml Adds explicit pymdown-extensions>=10.21.2,<11 lower-bound to the docs dependency group to ensure the pygments 2.20.0 compatibility fix is resolved; version range is well-bounded.
uv.lock Lockfile updated consistently: revision bumped 2→3, pymdown-extensions added to docs group entries, version pinned to 10.21.2 with correct PyPI URLs and SHA256 hashes.

Sequence Diagram

sequenceDiagram
    participant uv as uv resolve
    participant pyproject as pyproject.toml
    participant mkdocs_material as mkdocs-material
    participant pymdown as pymdown-extensions
    participant pygments as pygments 2.20.0

    uv->>pyproject: read docs dependency group
    pyproject-->>uv: pymdown-extensions>=10.21.2,<11 (explicit)
    uv->>mkdocs_material: resolve transitive deps
    mkdocs_material-->>pymdown: requires pymdown-extensions
    uv->>pymdown: satisfies >=10.21.2 → resolves 10.21.2
    pymdown->>pygments: calls HtmlFormatter with filename=""
    pygments-->>pymdown: renders syntax-highlighted code blocks
    pymdown-->>mkdocs_material: markdown extensions processed
    Note over pymdown,pygments: 10.21.2 coerces None to "" before passing to pygments, fixing the crash
Loading

Reviews (4): Last reviewed commit: "Merge branch 'main' into fix/bump-pymdow..." | Re-trigger Greptile

Pygments 2.20.0 (released 2026-03-29 as a security fix) introduced
stricter handling of `filename=None` in `HtmlFormatter`, which caused
`mkdocs build` to crash when rendering code reference pages.

pymdown-extensions 10.21.2 (also released 2026-03-29) fixes this by
coercing `None` to `""` before passing to pygments. Since
pymdown-extensions is a transitive dependency (via mkdocs-material and
mkdocstrings), we add an explicit lower-bound constraint to ensure the
compatible version is resolved.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@eric-tramel eric-tramel force-pushed the fix/bump-pymdown-extensions-for-pygments-compat branch from cec1b73 to 65439f7 Compare March 31, 2026 17:44
@eric-tramel eric-tramel merged commit 3be5e82 into main Mar 31, 2026
47 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants