chore(lint): make Markdown Prettier-safe and re-enable it (stage one: no line wrapping)#129
Open
taminomara wants to merge 1 commit into
Open
Conversation
PR testdouble#127 took Markdown out of Prettier's scope because running it corrupted files that agents read as raw source. Two of Prettier's normalizations are core CommonMark rules that cannot be turned off (ordered-list renumbering and inline-code-span trimming), so the fix is to make the source robust to them rather than to configure them away. With that done, Prettier formats this repo's Markdown without changing what any file says. Config: - .prettierrc.json: proseWrap "preserve" (no paragraph reflow, so the reformat stays small) and embeddedLanguageFormatting "off" (leave fenced code alone). - .prettierignore: stop excluding *.md; ignore the schematic html-template.html that Prettier hard-errors on (the prek hook never hands it over, but a direct `prettier .` would). - .pre-commit-config.yaml: update the stale comment that said Markdown is excluded. Content made robust to the two un-disable-able normalizations: - coding-standard: fix the Step 5 list numbering (1,2,4,5 -> 1,2,3,4). - project-documentation, plan-a-feature: give the ordered lists that a lead-in sentence interrupts a valid start, so Prettier keeps them as lists instead of collapsing them into a run-on paragraph. - work-item / issue templates: drop the ` — ` code span from the prose (the em-dash heading format is already shown in the template above) and keep the "em-dash with surrounding spaces" wording. - overview-template, script-execution-instructions, writing-effective- instructions: 4-backtick fences around Markdown examples that nest a fence, so the inner fence no longer closes the outer block early. - readability-editor, markdown-to-confluence, project-documentation: reword inline code spans Prettier would re-delimit. - context-injection-commands: drop the redundant padding spaces inside a double-backtick code span (they do not render, and Prettier strips them). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AhopKKK5YVPzmkdAzHtPcG
taminomara
changed the title
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.
What
Re-enables Prettier over Markdown (disabled in #127), after making the source robust to the two CommonMark normalizations Prettier cannot turn off.
This PR re-enables prettier, but doesn't enable line wrap to keep initial diff small and easily review-able. I'll send line wrap as a separate PR.
Why
#127 took Markdown out of Prettier's scope because running it corrupted files that agents read as raw source. Two of Prettier's normalizations are core CommonMark rules that survive every config — ordered-list renumbering and inline-code-span trimming. Rather than try to configure them away (impossible), this makes the source robust to them, so Prettier formats this repo's Markdown without changing what any file says.
What's in this PR
Config
.prettierrc.json:proseWrap: "preserve"(no paragraph reflow, so the eventual reformat stays small) andembeddedLanguageFormatting: "off"(leave fenced code examples alone)..prettierignore: stop excluding*.md; ignore the schematichtml-summary/references/html-template.htmlthat Prettier hard-errors on..pre-commit-config.yaml: update the stale comment that said Markdown was excluded.Content made robust to the two un-disable-able normalizations
coding-standard: fix the Step 5 list numbering (1,2,4,5→1,2,3,4).project-documentation,plan-a-feature: give the ordered lists that a lead-in sentence interrupts a valid start, so Prettier keeps them as lists instead of collapsing them into a run-on paragraph.work-item/issuetemplates: drop the` — `code span from the prose (the em-dash heading format is already shown in the template above) and keep the "em-dash with surrounding spaces" wording.overview-template,script-execution-instructions,writing-effective-instructions: use 4-backtick fences around Markdown examples that nest a fence, so the inner fence no longer closes the outer block early (these render broken today).readability-editor,markdown-to-confluence,project-documentation: reword inline code spans Prettier would re-delimit.context-injection-commands: drop redundant padding spaces inside a double-backtick code span.Sequencing / CI
This PR re-enables Prettier on Markdown but deliberately does not include the mechanical, repo-wide reformat — that rides in a separate PR to keep this one reviewable. As a result, the
lintjob is expected to be red on this branch until the reformat lands. Intended to be stacked with / merged alongside the reformat PR.🤖 Generated with Claude Code
https://claude.ai/code/session_01AhopKKK5YVPzmkdAzHtPcG