Add draft style guide for the docs site

.github/STYLE.md

@@ -0,0 +1,153 @@
+# Style guide for Mocha's docs site
+
+A short, maintainer-focused reference for writing pages under [`docs/src/content/docs/`](../docs/src/content/docs/).
+Its purpose is to reduce decision fatigue and to be cited in PR reviews instead of relitigating the same choices each time.
+
+This is a **draft** addressing [#5446](https://github.com/mochajs/mocha/issues/5446).
+Each rule below either codifies what the docs already mostly do, or picks a direction on an axis where current pages disagree.
+Inconsistent pages will be normalized in follow-up bulk-rename PRs once this guide is approved — see [Decisions that reconcile existing inconsistencies](#decisions-that-reconcile-existing-inconsistencies).
+
+When this guide is silent, look at how the [Astro Starlight docs](https://starlight.astro.build/) — the platform powering this site — write the same kind of content, and match that.
+
+---
+
+## 1. Sentence case for titles and headings
+
+Sentence case removes the "is _into_ capitalized?" ambiguity of title case.
+It is also the predominant style in Starlight's own documentation (e.g. the [Sidebar Navigation guide](https://starlight.astro.build/guides/sidebar/) uses H2s such as `Default sidebar`, `Add links and link groups`, `Autogenerated links`) and — more importantly — it is _already_ the convention used by Mocha's own sidebar labels in [`docs/astro.config.ts`](../docs/astro.config.ts): `Dynamic tests`, `Arrow functions`, `Compilers deprecation`, `Find global leaks`, `Run cycle overview`, etc.
+The page titles in frontmatter are the thing that has fallen out of sync.
+
+✅ `title: Find global leaks` — [`explainers/find-global-leaks.mdx`](../docs/src/content/docs/explainers/find-global-leaks.mdx)
+
+❌ `title: Parallel Mode` — [`features/parallel-mode.mdx`](../docs/src/content/docs/features/parallel-mode.mdx) (will be renamed to `Parallel mode`)
+
+Keep original casing for proper nouns, acronyms, reporter names, and CLI/tool names: `TypeScript`, `Node.js`, `BDD`, `TDD`, `XUnit`, `JSON`, `HTML`, `TAP`, `QUnit`, `Spec`, `Dot`, `Nyan`, `npm`.
+
+## 2. Imperative voice for action pages; noun phrase for concept pages
+
+Action-oriented pages (how-tos, troubleshooting) start with a verb.
+Reference and concept pages name a thing.
+
+✅ Action: `Find global leaks` — [`explainers/find-global-leaks.mdx`](../docs/src/content/docs/explainers/find-global-leaks.mdx)
+
+✅ Concept: `Global fixtures`, `Hooks`, `Reporters`
+
+❌ Gerund for an action page: `## Working with Promises` — [`features/asynchronous-code.mdx`](../docs/src/content/docs/features/asynchronous-code.mdx) (will become `## Work with promises`)
+
+## 3. Use `js`, `bash`, `ts` for code fences
+
+These are the dominant choices already in the docs (`js` 68×, `javascript` 15×; `bash` 16×, `sh` 0×).
+Pick the short forms consistently.
+
+✅ <code>&#96;&#96;&#96;js</code>, <code>&#96;&#96;&#96;bash</code>, <code>&#96;&#96;&#96;ts</code>
+
+❌ <code>&#96;&#96;&#96;javascript</code> &mdash; [`explainers/programmatic-usage.mdx`](../docs/src/content/docs/explainers/programmatic-usage.mdx) (will be normalized to `js`)
+
+## 4. Prefer ESM and `node:` core imports in examples
+
+ESM with `node:`-prefixed core imports is the modern Node default and is already used by most examples.
+Reach for CJS (`require`) only when illustrating CJS-specific behavior.
+
+✅ `import assert from "node:assert";` &mdash; [`declaring/dynamic-tests.mdx`](../docs/src/content/docs/declaring/dynamic-tests.mdx)
+
+❌ `const assert = require("assert");` (outside a CJS-specific example)
+
+## 5. Avoid filler and dismissive language
+
+The previous Eleventy-based docs site linted these words via `@11ty/eleventy-plugin-inclusive-language`; the lint did not survive the migration to Astro/Starlight, but the word list is still good guidance and is the one [reproduced in #5446](https://github.com/mochajs/mocha/issues/5446):
+
+`simply`, `obviously`, `basically`, `of course`, `clearly`, `everyone knows`, `however`, `easy`
+
+✅ "To use it, load this file when running Mocha via `mocha --require fixtures.cjs`."
+
+❌ "It's easy to use it &mdash; simply load this file..."
+
+## 6. Put version notes in a Starlight admonition, at the top
+
+`:::note[New in vX.Y.Z]` is the established convention.
+Use it instead of burying compatibility in mid-paragraph prose.
+
+✅
+
+```mdx
+:::note[New in v8.0.0]
+:::
+```
+
+&mdash; [`features/parallel-mode.mdx`](../docs/src/content/docs/features/parallel-mode.mdx)
+
+❌ "In v8.0.0 or newer, parallel mode is available…" (only in prose, no admonition)
+
+## 7. Internal links are root-relative and have no `.mdx` extension
+
+Starlight resolves Markdown links by the page's published URL, not its source path.
+Root-relative links without an extension survive file moves.
+
+✅ `[parallel mode](/features/parallel-mode)` &mdash; [`features/global-fixtures.mdx`](../docs/src/content/docs/features/global-fixtures.mdx)
+
+❌ `[parallel mode](../features/parallel-mode.mdx)`
+
+## 8. CLI flags: link on first mention, then bare code
+
+First mention of a flag in a page links to its `/running/cli` anchor; subsequent mentions are bare inline code.
+
+✅ "...via the [`--parallel`](/running/cli#--parallel--p) flag" (first mention), then later just "When `--parallel` is set, …"
+
+❌ Re-linking `--parallel` every time it appears, or never linking it at all.
+
+## 9. Label multi-file code samples with a leading filename comment
+
+The docs consistently put `// path/filename.ext` on the first line of a code block when the file identity matters.
+Keep that pattern instead of introducing a prose lead-in or a sub-heading.
+
+✅
+
+```js
+// test/hooks.mjs
+
+export const mochaHooks = {
+  beforeEach() {},
+};
+```
+
+&mdash; [`features/root-hook-plugins.mdx`](../docs/src/content/docs/features/root-hook-plugins.mdx)
+
+❌ A `### test/hooks.mjs` heading directly above the block.
+
+## 10. One sentence per line in prose
+
+Matches [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`DEVELOPMENT.md`](./DEVELOPMENT.md), and the majority of existing docs pages.
+Easier to diff, easier to translate, and removes hard-wrap arguments.
+
+✅
+
+```mdx
+In some cases, you may want a hook before (or after) every test in every file.
+These are called _root hooks_.
+```
+
+&mdash; [`features/root-hook-plugins.mdx`](../docs/src/content/docs/features/root-hook-plugins.mdx)
+
+❌ Wrapping a paragraph onto a single line, or hard-wrapping at 80 columns.
+
+---
+
+## Decisions that reconcile existing inconsistencies
+
+The rules above pick a direction on a few axes where current pages currently disagree.
+These will be addressed in follow-up bulk-rename PRs once this guide is approved:
+
+- **Heading case → sentence case.**
+  ~30 page titles and most H2 headings are currently title case (`Parallel Mode`, `Global Fixtures`, `## Working with Promises`).
+  ~12 already use sentence case (`Find global leaks`, `Global variables`, `Compilers deprecation`).
+  Follow-up PR: rename to sentence case across the board, preserving proper nouns and reporter/CLI names.
+
+- **Action-page voice → imperative.**
+  Today `Find global leaks` (imperative) sits next to `Counting assertions` and `Stubbing stdout` (gerunds) in the same `explainers/` folder.
+  Follow-up PR: `Count assertions`, `Stub stdout`, `## Work with promises`, etc.
+
+- **Code-fence language → `js`.**
+  15 remaining occurrences of <code>&#96;&#96;&#96;javascript</code> &mdash; concentrated in [`explainers/programmatic-usage.mdx`](../docs/src/content/docs/explainers/programmatic-usage.mdx), [`explainers/spies.mdx`](../docs/src/content/docs/explainers/spies.mdx), [`explainers/third-party-uis.mdx`](../docs/src/content/docs/explainers/third-party-uis.mdx) &mdash; will be normalized to <code>&#96;&#96;&#96;js</code>.
+
+This guide reflects the sentence-case preference [@mark-wiemer expressed in #5446](https://github.com/mochajs/mocha/issues/5446).
+The follow-up rename PRs are deliberately separated so the guide itself can be reviewed without diff noise.