Repository navigation
style: adapt prettier markdown formatting - #1689
Conversation
#1688 left Prettier formatting code inside fenced blocks with Prettier's own defaults rather than Biome's. Nothing on main revealed it, because every fence here was YAML, but a JavaScript example rewrites to double quotes and semicolons — contradicting the style of the very code it documents. Mirror `javascript.formatter` from biome.jsonc in `.prettierrc.yml`. Prettier applies `singleQuote` to YAML as well, and it cannot scope quote style per embedded language, so the config examples normalize to single quotes. That matches the repository's own YAML, which runs 260 single-quoted values to 38, including the `.github/release-drafter.yml` that the README documents. Quoting that carries meaning is untouched: Prettier keeps `change-authors-separator: "\n "` double-quoted, since single quotes in YAML do not process escapes.
cchanche
left a comment
There was a problem hiding this comment.
Why not scope prettier to .md files only ?
.prettierignore
# Ignore everything
*
# ...except markdown files:
!**/*.md
Per review: make the ignore file, not just the script globs, enforce that Prettier only ever touches Markdown. Two adjustments to the suggested pattern. `!*/` is required, because gitignore semantics cannot re-include a file whose parent directory is excluded, so `*` plus `!**/*.md` alone silently skips every Markdown file outside the repository root — 5 of 8 files here. And `!**/*.md` re-includes the release note templates under build-release-payload/static, which ship to users as content, so those are excluded again afterwards.
The template was excluded from Prettier because formatting it broke the output. Both alert markers sat directly above their prose, so `proseWrap: always` pulled them into the paragraph, and GitHub stopped rendering the alerts entirely — 2 alert blocks became 0, leaving a literal `[!WARNING]` in the release body. This is release content, not documentation: build-release-payload splices it into the body whenever no previous release is found. Separate the markers with a blank quote line, which is stable under Prettier, so the file can be formatted like every other Markdown file. Verified against GitHub's own renderer: both alerts still render and the rendered text is identical before and after, including after `$OWNER/$REPOSITORY` substitution. Also simplify the ignore file. `!*.md` matches at any depth, so the explicit generated directories were unnecessary — none of them contain Markdown, and the `*` baseline already excludes everything that is not re-included. Inline snapshots for the four affected e2e release bodies updated accordingly.
|
Followed up on the Why it was excluded, concretelyThe template is two GitHub alerts whose markers sat directly above their prose, which is exactly what
Users would have seen the literal marker text in their release notes. This is release content rather than documentation: FixSeparating the markers with a blank quote line makes the file stable under Prettier, so it no longer needs excluding. Verified through
The four affected e2e inline snapshots were regenerated; the diff is confined to the template region. Ignore file simplifiedDown to three lines:
On the question of a config-level way to express "Markdown only": there isn't one. Prettier's full option list from |
`proseWrap: always` rewrapped prose that read fine as written, and because a URL cannot be broken, it pushed long links onto a line of their own. No print width avoids that: the "open an issue" line in the release note template is 167 characters, so it only survives intact at printWidth 200. Switch to `preserve`. Prettier still normalizes structure — table alignment, list markers, escaping — but leaves authored line breaks alone. Every Markdown file in the repository is already byte-identical under it, so there is no churn. This also removes the reason the release note template needed reflowing, so 9f0555b's changes to it, and to the four e2e snapshots that assert its text, are reverted: the template, the snapshots, and the bundle are back to their previous bytes. The template no longer needs excluding either, since `preserve` cannot join `> [!WARNING]` into the prose that follows it — the alert-breaking hazard does not exist without reflowing. Wrap width is no longer machine-enforced for prose. Raising it was measured at roughly 550 reflowed lines and would also desync fenced code from Biome's lineWidth of 80, since printWidth governs both.
|
Switched to Why no width setting fixes itPrettier breaks before a long link because it cannot break inside a URL. The "open an issue" line in the release note template is 167 characters, so no sensible width keeps it intact:
Raising the width is also not free in general: measured at roughly 550 reflowed lines across the docs, and since What
|
Four alert markers ended in two spaces, a markdown hard break that existed to stop `proseWrap: always` joining the marker into the prose below it. With `proseWrap: preserve` nothing joins, so the hard break protects nothing and is just invisible whitespace that any editor trimming trailing space would remove. Verified against GitHub's renderer: all four markers still render as alerts, and the rendered text of both files is byte-identical before and after. These were the only trailing-whitespace hard breaks in any Markdown file in the repository.
|
I ended up fixing the configs and ignore. Hopefully this aligns better with what you asked for @cchanche |
|
Thank you ! |
Summary
Follow-up to #1688. That PR left Prettier formatting code inside fenced blocks, which is desirable — but Prettier formats it with its own defaults, not Biome's. Nothing on
mainexposed the gap, because every fence here is YAML. A JavaScript fence does:Double quotes and semicolons, contradicting
biome.jsonc(quoteStyle: single,semicolons: asNeeded) — the style of the very code the example documents. This surfaced while rebasing #1684, which adds the firstjsfence to the README.Fix
Mirror
javascript.formatterfrombiome.jsoncin.prettierrc.yml, with a comment noting the two must stay in sync.Why the YAML examples changed
Prettier applies
singleQuoteto YAML too, and it cannot scope quote style per embedded language — so this normalizes the config examples to single quotes. That is a real 168-line diff, and worth reviewing deliberately, but it moves the docs toward the repository's own convention:.yml/.yamlfiles.github/release-drafter.yml— the canonical instance of the config the README documents — is single-quoted throughout, so the examples now match what maintainers actually write.Quoting that carries meaning is preserved
In YAML, single quotes do not process escapes, so a blind conversion would corrupt values. Prettier is value-aware and does not do that:
README.md:322keepschange-authors-separator: "\n "double-quoted for exactly this reason. No line containing a backslash appears anywhere in the diff.Alternative considered
embeddedLanguageFormatting: 'off'would fix the JS problem with zero churn, but gives up machine-formatted YAML examples entirely. Mirroring the style keeps the examples enforced and consistent with the codebase.Verification
npm run allpasses,npm run check:cleanexits 0, andnpm run format:md:checkis idempotent.Note
Align fenced code block formatting with repo code style via Prettier config
Adds a .prettierrc.yml config to enforce single quotes, no semicolons, trailing commas, and consistent bracket/arrow formatting across JS/TS. Updates code examples in README.md and docs/configuration-loading.md to match the new style.
Changes since #1689 opened
.prettierignoreto simplify ignore patterns by removing explicit directory and file exclusions while maintaining global ignore with selective re-inclusion of markdown files [9f0555b]last-not-found.mdmarkdown template to include blank lines after blockquote markers and reflowed long lines into multiple wrapped lines [9f0555b]last-not-found.mdMarkdown template and updated corresponding test snapshots [1256f9a]Macroscope summarized c83b0ad.