fix(docs): enable admonition extension; fix DI steer line breaks#49
Merged
Conversation
Two rendering bugs in the DI steer shipped in #48. 1. modern-python.org was serving the literal text '!!! tip "Which one should I use?"' with the body as a raw code block. The admonition extension was never enabled in mkdocs.yml -- the site had no other admonition, so nothing had caught it. mkdocs build --strict passes either way, since a fell-through block is valid markdown, just not the markdown you meant. 2. On the org profile, GitHub renders a single newline as <br>, so the hard-wrapped paragraph broke mid-sentence in 8 places. The rest of profile/README.md avoids this by leaving prose unwrapped. Both surfaces now carry the steer as two blank-line-separated paragraphs, which renders identically under GFM and Python-Markdown with no <br> tricks. Verified: profile renders 4 tables, 0 <br>, 2 <p>; the site renders a real <div class="admonition tip"> with title + 2 paragraphs and no literal '!!!'.
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.
Two rendering bugs in the DI steer that shipped in #48. One is currently live.
1. modern-python.org is serving raw markup
The
admonitionextension was never enabled inmkdocs.yml(onlyattr_list,md_in_html,pymdownx.emoji). So the!!! tipblock fell through as literal text — the site right now renders:…followed by the body as a raw
<pre><code>block. Confirmed against the live site.mkdocs build --strictpassed the whole time, because a fell-through admonition is still valid markdown — just not the markdown you meant. The site had no other admonition anywhere, so nothing had ever exercised the extension.2. GitHub turned my line wraps into
<br>GFM renders a single newline as
<br>, so the hard-wrapped steer broke mid-sentence in 8 places ("...first-class: the" / "...awaitare built"). The rest ofprofile/README.mdsidesteps this by leaving prose unwrapped — the tagline is a single 173-char line.Fix
Enable
admonition, and write the steer as two blank-line-separated paragraphs on both surfaces. That renders identically under GFM and Python-Markdown, as two real<p>blocks, with no<br>tricks and no reliance on how each parser treats newlines.Verification
Rendered both surfaces and inspected the HTML, rather than trusting the build:
profile/README.mdvia GitHub's markdown API<table>, 0<br>, 2<p>in the steersite/index.html<div class="admonition tip">with title + 2 paragraphs; no literal!!!just check-planning: OK.mkdocs build --strict: clean.