fix(docs): enable admonition extension so !!! blocks render#214
Merged
Conversation
The 'admonition' Markdown extension was never enabled, so every !!! note/ warning/caution across 7 pages rendered as literal text — and code fences nested inside them broke (e.g. context.md). Add 'admonition' + the standard 'pymdownx.details' pairing. Verified: mkdocs --strict clean, 14 admonition blocks and 11 tab-sets now render, no literal !!! or broken fences remain. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
lesnik512
added a commit
that referenced
this pull request
Jun 14, 2026
Adds a 'docs-build' just recipe (uvx + docs/requirements.txt, mkdocs build --strict) and a 'docs' job to the reusable _checks workflow, so broken links, missing nav entries, and config errors fail CI on every PR. CI previously only ran lint + pytest and never built the docs, so the recent admonition-extension regression (#214) would not have been caught. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
lesnik512
added a commit
that referenced
this pull request
Jun 14, 2026
Adds a 'docs-build' just recipe (uvx + docs/requirements.txt, mkdocs build --strict) and a 'docs' job to the reusable _checks workflow, so broken links, missing nav entries, and config errors fail CI on every PR. CI previously only ran lint + pytest and never built the docs, so the recent admonition-extension regression (#214) would not have been caught. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Problem
While verifying the docs site renders correctly after the UX audit work, I found a pre-existing site-wide bug: the
admonitionMarkdown extension was never enabled inmkdocs.yml. Every!!! note/!!! warning/!!! cautionblock — used on 7 pages (to-1.x,to-2.x,alias,context,factories,lifecycle,fixtures) — rendered as literal text instead of a styled callout. As a downstream effect, code fences nested inside those admonitions (e.g. the context-propagation example) rendered as brokenlanguage-textblocks showing literal```python.Fix
Add
admonitionand the standardpymdownx.detailspairing tomarkdown_extensions.Verification (local
mkdocs build --strict)<p>!!! …admonitions; context.md had 4 broken code fences.🤖 Generated with Claude Code