chore(CI): stop running Prettier over Markdown - #127
Merged
Conversation
Prettier's Markdown config landed in #120 but was never applied, so the lint job has failed on every branch since. Applying it is not a mechanical reformat: it corrupts instructional content, because agents read skills and reference files as raw source, and a transform that renders the same can still change what an agent is told to do. Two of its transforms cannot be configured away, being core CommonMark normalizations: - It renumbers ordered lists. In coding-standard/SKILL.md step 4 becomes step 3, while that file's prose still points at "Step 6" and "Step 7". - It strips the spaces inside inline code spans, so the issue-heading spec ` — ` becomes `—` beside prose that still reads "with surrounding spaces". Both survive proseWrap: preserve and embeddedLanguageFormatting: off, so Markdown leaves Prettier's scope entirely. Prettier keeps JSON, YAML, and JS, which is the 10-file reformat here. The Markdown-only options in .prettierrc.json are now dead and removed, and the hook comments that claimed Prettier owns Markdown are corrected.
Collaborator
Author
|
@taminomara unfortunately, the prettier config to manage line length in markdown files isn't going to work. for now, i've disabled the prettier config's editing of markdown files with this PR. see the description for detail on what breaks when trying to run prettier on the current files in this repo |
Contributor
|
Oh no :( Thank you for catching this! I did spot-checks in formatted files, but missed these two.
Arguably, that's a bug in the skill itself, and an easily fixable one.
Yeah, that's technically a correct CommonMark normalization. We can try and work around it by changing the prose. It seems that all issues are around prose re-explaining what's already in template; we can change it so that it doesn't repeat literal template snippets.
Arguably, prose reflow was the biggest win. Will you accept a PR that re-enables it if I change wording to fix these issues? |
taminomara
added a commit
to taminomara/han
that referenced
this pull request
Jul 28, 2026
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. Reconstructed on the v5.0.0-alpha line, whose Markdown was already authored Prettier-safe: enabling the formatter changes only cosmetics, with no meaning-changing normalization anywhere in the tree. Prettier reformats eight files -- table-column re-alignment in README, docs/{evidence,readability,sizing, yagni}, skill-description-frontmatter, and han-research/research, plus one list-continuation indent fix in code-overview-to-confluence. The per-file v4 source hardening the original PR carried is unneeded here because no v5 file triggers either normalization. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017NEQjJUi7ZHVXGfVGXKUVJ
taminomara
added a commit
to taminomara/han
that referenced
this pull request
Jul 28, 2026
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
mxriverlynn
added a commit
that referenced
this pull request
Jul 29, 2026
… no line wrapping) (#129) ## 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.com/claude-code) https://claude.ai/code/session_017NEQjJUi7ZHVXGfVGXKUVJ
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
2 participants
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.
Prettier reformat: failure modes
Han's
lintjob has failed on every branch, includingmain, since CI landed in #120. The prettier config(
proseWrap: "always", printWidth 120) was added but never actually run against the repo. Applying it touches 281files (+28,218 / -12,660).
This report categorizes what that reformat actually does, based on the diffs verified against the working tree.
The thing to hold onto: prettier keeps the rendered page the same, but han's markdown is read as raw text by agents.
Three of these categories change the raw text in ways that matter.
1. Harmless reformatting
Rewraps paragraphs at 120 characters, swaps
*word*for_word_, pads out tables, tidies blockquotes. This is most ofthe 28k-line diff. The words don't change, so nothing breaks. It just makes every future doc diff noisy.
2. Frontmatter re-quoting
Rewrites the
description:field at the top of each skill file from double quotes to single quotes. This one warrantedchecking, since that field is what Claude reads to decide when to run a skill. All 103 frontmatter blocks were parsed
before and after with a YAML parser: the values come out identical. Safe.
3. Renumbered steps
Prettier renumbers ordered lists. In
han-coding/skills/coding-standard/SKILL.md, step 4 becomes step 3 — but thesentences around it still say "Step 6" and "Step 7". Those now point at the wrong steps, in a file Claude follows as
instructions. Nothing errors; the skill just quietly does the wrong step. This is the worst one.
Note that
.pre-commit-config.yamllists "ordered-list numbering" as something prettier is meant to own, which is thedirect conflict.
4. Mangled code snippets
Prettier strips the spaces inside
` — `, turning it into`—`. In two work-item templates that snippet isthe heading format, and the sentence next to it still says "em-dash with surrounding spaces." The source now shows the
opposite of what the text says.
It also garbles backticks in docs that explain markdown itself, including
readability-editor.md— the doc whose job isto say "leave code fences byte-for-byte unchanged."
Affected:
work-items-to-issues/references/issue-template.md,plan-work-items/references/work-item-template.md,markdown-to-confluence/SKILL.md,code-overview/references/overview-template.md,han-core/agents/readability-editor.md,project-documentation/SKILL.md, and three guidance references underhan-plugin-builder/.5. Rewritten code examples
Prettier reaches inside fenced code blocks and restyles the code: collapsing JSON arrays, flipping
'base'to"base",shifting HTML spacing. Those examples are specs, so restyling them is wrong — but this one turns off with
embeddedLanguageFormatting: "off".Affected:
plugin-json-options.md,html-summary/SKILL.md,html-summary/references/report-style.md.6. A file prettier can't read
han-reporting/skills/html-summary/references/html-template.htmlis a schematic sketch, not real HTML, and prettierhard-errors on it (exit 2). Not a CI problem today, because the prek hook only hands prettier markdown, JSON, YAML, and
JS. It would break if anyone widens that list.
Bottom line
Categories 1 and 2 are just noise. Category 5 has a config switch. Categories 3 and 4 are the blockers, and neither
can be turned off — both still happen under the safest config available (
proseWrap: preserveplusembeddedLanguageFormatting: off), because they are core CommonMark normalizations.No prettier setting formats this repo's markdown without breaking it. Recommendation: take markdown out of prettier's
scope and keep it on JSON, YAML, and JS — a clean 10-file diff that turns lint green.
Related
Its
lintjob is still red on prettier alone, pending this decision.