Skip to content

fix(markdown):render common prose as written - #58

Merged
ikelaiah merged 2 commits into
mainfrom
fix/reader-fidelity
Nov 5, 2026
Merged

ikelaiah merged 2 commits into
mainfrom
fix/reader-fidelity

Conversation

@ikelaiah

@ikelaiah ikelaiah commented Nov 5, 2026

Copy link
Copy Markdown
Owner

Common Markdown in real READMEs and docs rendered incorrectly without any error. This makes it render as written, and fixes two small CLI/config bugs.

Rendering

  • ## Learn C# keeps its # (a closing hash run now needs a space before it).
  • Titles, outline and search keep underscores (snake_case). Anchors are unchanged, so existing #fragment links keep working. GitHub-style anchors would be a 2.0 change.
  • $5 and $10 stays prose: inline math follows Pandoc's delimiter rule.
  • 2 * 3 * 4 stays literal: emphasis delimiters must touch their text.
  • Link and image targets keep balanced parentheses (Wikipedia URLs).
  • Fenced code indented under a list item renders inside that item.
  • ~~~ fences are supported; a block closes only on its opening marker.

Other fixes

  • project.description: null no longer produces a "None" meta description.
  • serve prints an unchanged rebuild failure once instead of every poll. The automatic retry from v1.1.9 is kept.
  • audit now reuses the renderer's fenced-code lines and link grammar instead of its own copies, so the two can't drift apart.

Reviewer notes

  • One existing expectation changed in test_straight_quote_in_image_target_is_escaped. The escaping assertions still hold; only the old truncation of alert(1) at the first ) changed.
  • > [!CAUTION] still stops the build, as documented.
  • Docs: docs/markdown-showcase.md explains each rule and uses a ~~~ block instead of the one-space-indent workaround. CHANGELOG "Unreleased" has an entry for each fix.

Checklist

  • Tests pass: python -m unittest discover -s tests (348 tests, run with PYTHONPATH=src)
  • Documentation checks pass: docsprout check and docsprout audit (0 errors, 0 warnings)
  • Guides, examples or migration notes updated when behaviour changes
  • For a release: version metadata, CHANGELOG.md, docs/versions.json and workflow pins updated together (not a release)
  • No secrets, tokens or credentials added

- Keep a trailing hash that belongs to a word in headings (C#, F#).
- Keep underscores in titles, outline and search; anchors unchanged.
- Treat prices such as $5 and $10 as prose (Pandoc math delimiters).
- Leave spaced asterisks literal instead of italicising.
- Allow balanced parentheses in link and image targets.
- Render fenced code indented under list items inside the item.
- Support ~~~ fences; close a block only on its opening marker.
- Share the renderer's code lines and link grammar with audit.
- Use an empty description when project.description is null.
- Print an unchanged preview rebuild failure once; keep retrying.
@ikelaiah ikelaiah self-assigned this Nov 5, 2026
@ikelaiah
ikelaiah merged commit 5102a5a into main Nov 5, 2026
32 checks passed
@ikelaiah ikelaiah mentioned this pull request Nov 5, 2026
5 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant