Skip to content

Fix admonitions by declaring Zensical's default Markdown extensions - #121

Open
LukasOro wants to merge 2 commits into
mainfrom
fix/markdown-extension-defaults
Open

Fix admonitions by declaring Zensical's default Markdown extensions#121
LukasOro wants to merge 2 commits into
mainfrom
fix/markdown-extension-defaults

Conversation

@LukasOro

@LukasOro LukasOro commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Problem

Paragraphs written as !!! note were rendering as literal text instead of as callouts, on introduction.md, get-started.md and mappings.md.

The Markdown was fine. The cause is in how Zensical resolves extension config (zensical/config.py):

config.get("markdown_extensions", DEFAULT_MARKDOWN_EXTENSIONS)

That is a fallback, not a merge. Zensical ships a default extension set that includes admonition, but the moment a project declares any markdown_extensions the whole default set is discarded and only the declared ones stay active. zensical.toml declared 8, so the other 14 defaults, admonition among them, were silently switched off.

Change

1. Declare the defaults explicitly. zensical.toml now lists the full effective extension set, with the inherited defaults fenced between BEGIN/END comments 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 whenever ZENSICAL_VERSION moves in the Makefile.

pymdownx.superfences (mermaid fence) and toc (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 like 1/2 wherever 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 in use-cases.md into 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.highlight restoring class="language-… highlight" and per-line __span / __codelineno anchors 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 the Makefile:

  • 3/3 admonitions render; no literal !!! left in any generated page
  • no smartsymbols glyphs in the output; the (a)/(b)/(c) enumeration reads correctly
  • 24 tabbed blocks and the mermaid diagram unaffected
  • site/spec/index.html byte-identical to before

Note for the reviewer

The (c\) escape added to docs/use-cases.md in the first commit is redundant once the second commit lands. It was left in place because it renders identically and re-protects the sentence if smartsymbols is ever switched back on, but it is easy to drop if you would rather have the plainer source.

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.
@LukasGold
LukasGold requested a review from raederan August 6, 2026 09:38
@LukasOro LukasOro self-assigned this Aug 6, 2026
@LukasOro LukasOro added bug Something isn't working documentation Improvements or additions to documentation labels Aug 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants