Skip to content

Add draft style guide for the docs site#6001

Draft
mostafaNazari702 wants to merge 1 commit into
mochajs:mainfrom
mostafaNazari702:docs/style-guide
Draft

Add draft style guide for the docs site#6001
mostafaNazari702 wants to merge 1 commit into
mochajs:mainfrom
mostafaNazari702:docs/style-guide

Conversation

@mostafaNazari702

@mostafaNazari702 mostafaNazari702 commented May 23, 2026

Copy link
Copy Markdown
Contributor

PR Checklist

Overview

Opening this as a draft first to get feedback/approval before doing any larger follow-up renames.

I cooked a short docs style guide in .github/STYLE.md to address #5446 and document the conventions the docs already mostly follow. each rule includes real "good" and "bad" examples pulled from the current docs in the latest main branch.

It covers stuff like:

  • sentence-case headings
  • action vs concept page naming
  • preferred code fence languages (js, bash, ts)
  • ESM + node: imports
  • avoiding filler/dismissive wording
  • consistent version notes, links, filenames, and prose formatting

the goal isnt to invent a brand-new style guide but rather to formalize existing patterns and resolve a few places where the docs are currently inconsistent.

no existing docs are modified yet so review stays focused and low-noise. if the direction looks good i can follow up with separate cleanup PRs for the inconsistencies mentioned at the bottom of the file.

Main feedback I'm looking for:

  • Is .github/STYLE.md the right location?
  • any rules you'd change/add/remove?
  • confirmation on the sentence-case direction before bulk renames.

P.S. AI (GPT-4o) 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.

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 <noreply@openai.com>
@mostafaNazari702

Copy link
Copy Markdown
Contributor Author

@mark-wiemer @JoshuaKGoldberg
What do you guys say?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant