Fix admonitions by declaring Zensical's default Markdown extensions - #121
Open
LukasOro wants to merge 2 commits into
Open
Fix admonitions by declaring Zensical's default Markdown extensions#121LukasOro wants to merge 2 commits into
LukasOro wants to merge 2 commits into
Conversation
Zensical resolves markdown_extensions with
`config.get("markdown_extensions", DEFAULT_MARKDOWN_EXTENSIONS)`, which is a
fallback rather than a merge. Because zensical.toml declared its own set, the
built-in defaults were replaced wholesale and every default left out was
silently switched off. "admonition" was one of them, so the `!!! note` blocks
in introduction.md, get-started.md and mappings.md rendered as literal text.
Restate the full default set in zensical.toml, fenced between BEGIN/END
comments so readers can tell the inherited upstream values apart from this
project's own choices, and note that the block needs re-checking whenever
ZENSICAL_VERSION changes in the Makefile. pymdownx.superfences and toc stay
outside the block because they are customized and TOML forbids defining the
same table twice.
Restoring the defaults also re-enables pymdownx.smartsymbols, which rewrote the
"(c)" of an (a)/(b)/(c) enumeration in use-cases.md into a copyright sign;
escape it as "(c\)" so it renders literally.
Verified against a full build: admonitions now render on all three pages, and
the only other change to the generated HTML is pymdownx.highlight restoring
language classes and per-line anchors on code blocks.
The extension rewrites (c), (r), (tm), +/-, -->, <-- , =/= and fractions such as 1/2 anywhere they occur in prose. On a specification site those sequences are usually real content rather than typographic shorthand: it already turned the "(c)" of an (a)/(b)/(c) enumeration in use-cases.md into a copyright sign, and since the substitution is silent the next occurrence is just as likely to reach a reader unnoticed. Keep the entry in the defaults block, commented out with the reasoning beside it, so it stays visible as a default that is off on purpose rather than one that was forgotten. Verified with a full build: no smartsymbols glyphs remain in the generated pages, and the admonitions are unaffected.
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
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
Paragraphs written as
!!! notewere rendering as literal text instead of as callouts, onintroduction.md,get-started.mdandmappings.md.The Markdown was fine. The cause is in how Zensical resolves extension config (
zensical/config.py):That is a fallback, not a merge. Zensical ships a default extension set that includes
admonition, but the moment a project declares anymarkdown_extensionsthe whole default set is discarded and only the declared ones stay active.zensical.tomldeclared 8, so the other 14 defaults,admonitionamong them, were silently switched off.Change
1. Declare the defaults explicitly.
zensical.tomlnow lists the full effective extension set, with the inherited defaults fenced betweenBEGIN/ENDcomments so a reader can tell upstream values apart from this project's own choices. The header explains the replace-not-merge behaviour and flags that the block needs re-checking wheneverZENSICAL_VERSIONmoves in theMakefile.pymdownx.superfences(mermaid fence) andtoc(permalink) are customized, so they sit in the project-specific block below instead: TOML forbids defining the same table twice. The defaults block names them so they aren't mistaken for non-defaults.2. Disable
pymdownx.smartsymbols(second commit). Restoring the defaults also restored this one, which rewrites(c),(r),(tm),+/-,-->,=/=and fractions like1/2wherever they appear in prose. On a spec site those sequences tend to be real content: it turned the(c)of an(a)/(b)/(c)enumeration inuse-cases.mdinto a copyright sign. Because the substitution is silent, the next occurrence would be just as easy to miss. The entry stays in the defaults block commented out, with the reasoning beside it, so it reads as off-on-purpose rather than forgotten.Effect on the built site
Diffed all 23 generated pages against a pre-change build. Beyond the three admonitions now rendering, exactly one other thing changed:
pymdownx.highlightrestoringclass="language-… highlight"and per-line__span/__codelinenoanchors on code blocks, across 11 pages. That is the markup Material's code copy/select and line-linking features expect, and it had been suppressed. No other prose was altered.Verification
Full
zensical@0.0.46 build --clean, matching the pinned version in theMakefile:!!!left in any generated page(a)/(b)/(c)enumeration reads correctlysite/spec/index.htmlbyte-identical to beforeNote for the reviewer
The
(c\)escape added todocs/use-cases.mdin the first commit is redundant once the second commit lands. It was left in place because it renders identically and re-protects the sentence ifsmartsymbolsis ever switched back on, but it is easy to drop if you would rather have the plainer source.