From e4d726ce489ba0ebe3d69236a96330d22e39f542 Mon Sep 17 00:00:00 2001 From: mostafanazari702 Date: Sat, 23 May 2026 13:29:09 +0200 Subject: [PATCH] docs: add draft style guide for the docs site AI was used responsibly to refine and restructure my original notes into a clearer, more readable format while following the conventions of a Markdown (.md) file. Co-authored-by: ChatGPT-4o --- .github/STYLE.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 .github/STYLE.md diff --git a/.github/STYLE.md b/.github/STYLE.md new file mode 100644 index 0000000000..670b58e121 --- /dev/null +++ b/.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. + +✅ ```js, ```bash, ```ts + +❌ ```javascript — [`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";` — [`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 — 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] +::: +``` + +— [`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)` — [`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() {}, +}; +``` + +— [`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_. +``` + +— [`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 ```javascript — 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) — will be normalized to ```js. + +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.