fix(docs): upgrade pymdown-extensions to 10.21.3 for pygments 2.20.0 compat#514
Merged
Conversation
…ht crash
The CD docs build crashed in mkdocstrings source highlighting:
html.escape('NoneType') via pygments 2.20.0's HtmlFormatter, which
escapes the 'filename' option (None for mkdocstrings source blocks)
without guarding None. Pin pygments < 2.20 (resolves to 2.19.2) in the
docs group to restore the build.
Validated locally: full CD docs sequence (vrg-docs-stage +
vrg-docs-patch-nav + mkdocs build) completes cleanly.
The pin is technical debt; revisit/unpin tracked in #513 (records the
broken version and how to validate a fix). Refs #512.
Supersedes the previous pygments<2.20 pin on this branch. Pinning pygments down was a dead end: pygments 2.19.2 carries CVE-2026-4539 (fixed in 2.20.0), so pip-audit blocks it. The actual incompatibility is pymdown-extensions < 10.21.3 passing filename=None into pygments' HtmlFormatter, which crashes mkdocstrings source highlighting on pygments >= 2.20.0. pymdown-extensions 10.21.3 fixes that. So: stay on pygments 2.20.0 (CVE-safe) and floor pymdown-extensions >= 10.21.3. Result: docs build is green AND audit is clean; no pinned-down dependency, so no tech debt (closes the need for #513). Validated locally via the full CD docs sequence (stage + patch-nav + mkdocs build) and vrg-validate (incl. pip-audit). Refs #512.
wphillipmoore-vergil-agent
Bot
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes the CD docs build crash (mkdocstrings source highlighting) surfaced once the item-7 CD fix (#511) un-blocked the docs job.
Root cause: pymdown-extensions < 10.21.3 passes
filename=Noneinto pygments' HtmlFormatter; pygments >= 2.20.0 callshtml.escape()on it and crashes (AttributeError: 'NoneType' ... 'replace'). pymdown-extensions 10.21.3 fixes the filename handling.Fix: floor
pymdown-extensions>=10.21.3and relock; stay on pygments 2.20.0, which also carries the CVE-2026-4539 fix. No pinned-down dependency, so no tech debt (pinning pygments<2.20 was a dead end — 2.19.2 fails pip-audit on that CVE).Validated locally: full CD docs sequence (vrg-docs-stage + vrg-docs-patch-nav + mkdocs build) builds clean, and vrg-validate (incl. pip-audit) passes. Closes #512. Supersedes the tech-debt issue #513 (no longer needed). Part of epic mq-rest-admin-project/.github#14.