chore(CI): stop running Prettier over Markdown#127
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.
|
@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 |
|
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? |
2 participants
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.