chore(lint): make Markdown Prettier-safe and re-enable it (stage one: no line wrapping) - #129
Merged
mxriverlynn merged 1 commit intoJul 29, 2026
Conversation
taminomara
marked this pull request as ready for review
July 14, 2026 23:31
taminomara
force-pushed
the
chore/reenable-prettier-markdown
branch
from
July 28, 2026 15:31
9099eef to
5b2ed69
Compare
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), and a fenced block also closes early when a ```markdown example embeds its own nested fence. The fix is to make the source robust to these rather than 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. - .pre-commit-config.yaml: update the stale comment that said Markdown is excluded. Cosmetic reformat (proseWrap preserve keeps it small): table-column re-alignment in README, docs/{evidence,readability,sizing,yagni}, skill-description-frontmatter, and han-research/research, plus a list-continuation indent fix in code-overview-to-confluence. Source made robust to the un-disable-able normalizations. An earlier repo-wide `prettier --write` (ab708a7) had already applied some of these to Markdown while it was still in scope, and later v5 authoring added new unsafe constructs; an audit of both surfaced four files that still render wrong or would be corrupted: - project-documentation, plan-a-feature: an ordered list that a lead-in sentence (or a "5a." sub-marker) interrupts had collapsed into a run-on paragraph; give each item a valid start on its own line so it renders as a list again. - overview-template, writing-effective-instructions: the ```markdown template examples embed a nested fence, so wrap each in a 4-backtick outer fence and the inner fence no longer closes the outer block early. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017NEQjJUi7ZHVXGfVGXKUVJ
taminomara
force-pushed
the
chore/reenable-prettier-markdown
branch
from
July 28, 2026 16:43
5b2ed69 to
554f6c5
Compare
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.
What
Re-enables Prettier over Markdown (disabled in #127), after making the source robust to the CommonMark normalizations Prettier cannot turn off.
Reconstructed onto
han-v5.0.0-alpha-1.mainis frozen until v5, so this PR targets the alpha line. Because v5's Markdown is already almost entirely Prettier-clean, re-enabling the formatter is nearly a no-op: the reformat is included here, touches only a handful of files, and CI is green — there is no separate repo-wide reformat PR to wait on.This is still stage one: no line wrapping (
proseWrap: preserve). Flipping to wrapped prose (proseWrap: always) stays a deliberately separate, later 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 — and a fenced block also closes early when a
```markdownexample embeds its own nested fence. Rather than try to configure these 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) 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.Cosmetic reformat (small, because v5's Markdown was already clean): table-column re-alignment in
README,docs/{evidence,readability,sizing,yagni},skill-description-frontmatter, andhan-research/research, plus a list-continuation indent fix incode-overview-to-confluence.Source made robust to the un-disable-able normalizations. An earlier repo-wide
prettier --write(ab708a7) had already applied some of these while Markdown was in scope, and later v5 authoring introduced new unsafe constructs. An audit of both surfaced four files that render wrong today or would be corrupted:project-documentation,plan-a-feature: an ordered list that a lead-in sentence (or a5a.sub-marker) interrupts had collapsed into a run-on paragraph; each item now has a valid start on its own line, so it renders as a list again.overview-template,writing-effective-instructions: the```markdowntemplate examples embed a nested fence, so each is wrapped in a 4-backtick outer fence and the inner fence no longer closes the outer block early (these render broken today).Audited and left unchanged — v5 already renders these safely:
coding-standard(its list is already sequential, and nothing references the items by number), thework-item/issueem-dash spans (the prose carries the "surrounding spaces" requirement),readability-editor,markdown-to-confluence,context-injection-commands, andscript-execution-instructions(already a 4-backtick fence). A sweep of every inline code span Prettier touched found no other corruption.CI
prettier --check .is green across the whole repo on this branch, so thelintjob should pass.🤖 Generated with Claude Code
https://claude.ai/code/session_017NEQjJUi7ZHVXGfVGXKUVJ