Repository navigation
docs: document markdown parsing for all front-matter strings - #927
Merged
Merged
Conversation
q2 parses any string-valued YAML entry as markdown, like Pandoc, not just the title. The rule was documented only for description:, so authors missed the same Q-1-20 failure in other keys. Document the general rule, the !str opt-out for verbatim text, and link the Q-1-20 page.
Contributor
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
cderv
added a commit
that referenced
this pull request
Oct 27, 2026
The writing-notes guidance from #927 overstated three things: - Not every front-matter string is markdown. ANNOTATIONS in meta_annotations.rs keeps machine-facing keys (listing.contents, the brand subtree, link-external-filter) as plain strings, so escaping them as markdown leaves literal backslashes in the value. - !str does not opt out everywhere. Presentation keys in MARKDOWN_CONFIG_PATHS (toc-title, site/sidebar titles, footer text) are re-parsed by ConfigMarkdownTransform, and a tagged string is indistinguishable from an untagged one by then: `toc-title: !str "the engines' state"` still fails a strict render with Q-1-20. - The possessive example put the apostrophe inside a code span, where it is code content and renders cleanly. The example is now the plain YAML string, which does fail with Q-1-20.
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.
Front-matter string values are parsed as markdown, not only
description:. The writing rule covered onlydescription:, so a possessive or unbalanced quote in another string key (title:, a sidebar label) fails with Q-1-20 and nothing in the rule points at that cause.Document the general rule, the
!strtag for text that must stay verbatim, and link the Q-1-20 page.Checked with
q2 render --strict claude-notes: all 1558 files render with no warnings.