Skip to content

chore(lint): make Markdown Prettier-safe and re-enable it (stage one: no line wrapping) - #129

Merged
mxriverlynn merged 1 commit into
testdouble:han-v5.0.0-alpha-1from
taminomara:chore/reenable-prettier-markdown
Jul 29, 2026
Merged

chore(lint): make Markdown Prettier-safe and re-enable it (stage one: no line wrapping)#129
mxriverlynn merged 1 commit into
testdouble:han-v5.0.0-alpha-1from
taminomara:chore/reenable-prettier-markdown

Conversation

@taminomara

@taminomara taminomara commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

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. main is 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 ```markdown example 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) and embeddedLanguageFormatting: "off" (leave fenced code examples alone).
  • .prettierignore: stop excluding *.md; ignore the schematic html-summary/references/html-template.html that 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, 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 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 a 5a. 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 ```markdown template 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), the work-item / issue em-dash spans (the prose carries the "surrounding spaces" requirement), readability-editor, markdown-to-confluence, context-injection-commands, and script-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 the lint job should pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_017NEQjJUi7ZHVXGfVGXKUVJ

@taminomara taminomara changed the title chore(lint): make Markdown Prettier-safe and re-enable it chore(lint): make Markdown Prettier-safe and re-enable it (stage one: no line wrapping) Jul 14, 2026
@taminomara
taminomara marked this pull request as ready for review July 14, 2026 23:31
@taminomara
taminomara force-pushed the chore/reenable-prettier-markdown branch from 9099eef to 5b2ed69 Compare July 28, 2026 15:31
@taminomara
taminomara changed the base branch from main to han-v5.0.0-alpha-1 July 28, 2026 15:31
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
taminomara force-pushed the chore/reenable-prettier-markdown branch from 5b2ed69 to 554f6c5 Compare July 28, 2026 16:43
@mxriverlynn
mxriverlynn merged commit c847d95 into testdouble:han-v5.0.0-alpha-1 Jul 29, 2026
2 checks passed
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.

2 participants