You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add Prettier to CI and apply formatting across all markdown + JSON
Why this exists
---------------
The previous commit (80ec6b3) disabled markdownlint's MD060
(table-column-style) rule with a stated condition for re-enabling
it: "If we add a markdown formatter to the lint pipeline later,
re-enable this rule." This commit satisfies that condition.
The 28 MD060 violations across AGENTS.md and ORG_SETTINGS.md were
all the same shape: a single cell length changing on a single row
broke the whole table's alignment. That's exactly the failure mode
auto-formatters exist to eliminate. Prettier's markdown printer
reformats every table to a consistent aligned style, so MD060 can
be enforced as a check against drift rather than as a manual
maintenance burden.
What's in this commit
---------------------
1. `.prettierrc` at the repo root pinning the formatter behaviour
that matters:
- printWidth: 80 (fits standard terminal/diff views).
- proseWrap: preserve - critical. Without this, Prettier would
reflow every paragraph on every save and produce huge
cross-cutting diffs that destroy git blame. Our prose is
wrapped intentionally for readability.
- tabWidth: 2, useTabs: false, endOfLine: lf, trailingComma:
all - house style that matches the rest of our ecosystem.
- embeddedLanguageFormatting: off for *.md / *.mdx so that
fenced code blocks (especially YAML and bash inside our
workflow examples) aren't reformatted by Prettier and put
into conflict with the original source.
2. `.prettierignore` at the repo root that excludes:
- YAML files. yamllint and actionlint enforce stricter
semantics on those (the `on:` truthy quirk in particular)
that Prettier doesn't understand. Letting both touch the
same files would produce conflicting expectations.
- LICENSE (verbatim text, must not be reformatted).
- CODEOWNERS files (have their own structural meaning that
Prettier doesn't model).
- Lockfiles and node_modules.
3. New `prettier --check` job in .github/workflows/lint.yml. Pinned
to prettier 3.3.3, installed globally on Node 20, runs against
`**/*.{md,mdx,json,jsonc}`. Should be a required status check on
main alongside the other four lint jobs.
4. Re-enabled `MD060: true` in `.markdownlint.jsonc`. Verified
locally that Prettier's table output satisfies markdownlint's
"aligned" style - 0 errors after `prettier --write` followed by
`markdownlint-cli2`.
5. The 11 files Prettier reformatted on this first run:
- AGENTS.md, CONTRIBUTING.md, ORG_SETTINGS.md, README.md,
SECURITY.md, SUPPORT.md, profile/README.md - tables
re-aligned, italics normalised from `*x*` to `_x_`.
- .markdownlint.jsonc - trailing comma per JSONC convention.
- workflow-templates/ci-docs-mdx.properties.json,
codeql.properties.json, dependency-review.properties.json -
arrays expanded to multi-line where they exceeded printWidth.
None of the changes alter rendered output.
Notable decisions
-----------------
- `--check` not `--write` in CI. Auto-fixing in CI would require
pushing a commit, which is its own surface (token scope, signed
commits, DCO trailer). `--check` fails fast and tells the
contributor to run `prettier --write` locally.
- Prettier scope is markdown + JSON only. NOT YAML. yamllint's
`truthy: { check-keys: false }` config and Prettier's YAML
printer disagree about how to render the GitHub Actions `on:`
key, and resolving that means picking one tool. yamllint wins
because actionlint depends on the same indentation conventions.
- Prettier 3.3.3 pinned. Dependabot (44dfac9) will track it via
GitHub Actions ecosystem updates triggered by changes to the
workflow file.
- Italics use `_underscores_` after this commit. That's Prettier's
default and not worth fighting. GitHub renders both identically.
What this deliberately does NOT do
----------------------------------
- Does NOT add a pre-commit hook to auto-format on commit. That's
a per-developer-machine concern; an org-wide default repo isn't
the place to mandate it. Anyone who wants one can add husky or
lefthook to their own repo.
- Does NOT format YAML. See above.
- Does NOT add Prettier as a reusable workflow. The same pattern
(a few lines of CI calling `npm install -g [email protected] &&
prettier --check`) is shorter than the reusable-workflow
invocation would be.
Cross-references
----------------
- README.md "Repo basics": new rows for `.prettierrc` and
`.prettierignore`.
- ORG_SETTINGS.md § required status checks should add `prettier
--check` to the list for this repo's main branch alongside the
existing four lint job names.
Closes the MD060 / "no markdown formatter" gap from the
merge-readiness review.
0 commit comments