Skip to content

Commit c4038cf

Browse files
alexandratranalexandratran
authored
Merge pull request #95 from Consensys/agent-readiness
Update template and guidance
2 parents 1d1b37a + 446a820 commit c4038cf

24 files changed

Lines changed: 3619 additions & 1041 deletions

‎.cursor/rules/content-types.mdc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
description: Maps folder conventions to Diataxis content types so AI tools produce the right structure for each doc category.
3+
globs: ["**/*.md", "**/*.mdx"]
4+
alwaysApply: false
5+
---
6+
7+
# Content types (Diataxis)
8+
9+
> **Note for this repository:** `docs-template` itself is a guide and template site — its content
10+
> is organized by task (`contribute/`, `create/`, `configure/`) rather than by Diataxis type.
11+
> The conventions below do **not** apply to files in this repo.
12+
> They are recommended for any **product documentation site** created using this template.
13+
14+
The [Diataxis framework](https://diataxis.fr/) organizes documentation by function. In a product
15+
docs site, the folder a file lives in determines the content type and structure expectations.
16+
17+
## Folder-to-type mapping
18+
19+
### `concepts/` - Explanation
20+
21+
- Explain **why** something exists and **how** it works at a high level.
22+
- Provide context: design decisions, historical reasons, trade-offs, and alternatives.
23+
- Make connections to other parts of the system or to broader industry concepts.
24+
- Do not include step-by-step instructions. Link to related guides or quickstarts instead.
25+
- Keep explanation closely bounded. Do not let instructions or reference details creep in.
26+
27+
### `how-to/` - How-to
28+
29+
- Goal-oriented steps that help the reader achieve a specific outcome.
30+
- Title the page with the goal (for example, "Configure rate limits"), not a generic label.
31+
- State the goal in the first sentence or heading.
32+
- List prerequisites before the first step.
33+
- Number the steps. Each step should contain one action.
34+
- Assume the reader has basic knowledge of the product.
35+
- Omit the unnecessary. Practical usability matters more than completeness.
36+
- Do not digress into explanations or teaching. Link to concept pages instead.
37+
38+
### `get-started/` - Onboarding
39+
40+
`get-started/` pages are onboarding essentials: installation, system requirements, connecting
41+
to services, and initial configuration.
42+
43+
Choose structure based on the topic (how-to steps, short explanation, or reference-style facts)
44+
and match conventions of neighboring pages in the same `get-started/` section.
45+
46+
### `reference/` - Reference
47+
48+
- Precise, complete, structured descriptions of APIs, CLI options, methods, and parameters.
49+
- Describe and only describe. Be austere, neutral, and factual.
50+
- Match the format used in surrounding reference pages.
51+
- Mirror the structure of the API or code itself (for example, one section per method or endpoint).
52+
- Include short usage examples to illustrate parameters and return values.
53+
- Keep explanatory prose to the minimum needed to use the API correctly.
54+
- Do not include tutorials or extended how-to steps.
55+
56+
### `tutorials/` - Tutorial
57+
58+
- Learning-oriented, reproducible, end-to-end walkthrough.
59+
- State what the reader will build or accomplish at the very start.
60+
- Do not assume the reader has prior knowledge of the subject or tools.
61+
- Deliver visible results early and often. Each step should produce output the reader can verify.
62+
- Show expected output (for example, "You should see `Connected`").
63+
- Ruthlessly minimize explanation. Keep the focus on doing, not theory. Link to concept pages for
64+
deeper understanding.
65+
- Ignore options and alternatives. Guide the reader along a single path to a successful conclusion.
66+
- Provide a complete working configuration or code sample.
67+
- Aspire to perfect reliability. Test every step.
68+
69+
## Frontmatter
70+
71+
For required and optional documentation frontmatter (`description`, `keywords`, `sidebar_label`,
72+
`title` vs duplicate H1), see **Frontmatter** in `markdown-formatting.mdc`.

‎.cursor/rules/contributor-workflow.mdc‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
description: Workflow rules for contributors and reviewers covering sidebar updates, redirects, verification, and PR expectations.
3+
alwaysApply: true
4+
---
5+
6+
# Contributor workflow
7+
8+
See [Submit a contribution](/contribute/submit-a-contribution) for the full contribution process.
9+
The rules below highlight the requirements that are most often missed.
10+
11+
## Sidebar updates
12+
13+
Sidebars are configured in `sidebars.js`. New pages may be autogenerated from the filesystem or
14+
require a manual entry, depending on the sidebar configuration used by this site.
15+
16+
To control ordering and labels, use `_category_.json` files in directories and
17+
`sidebar_position` / `sidebar_label` in page frontmatter.
18+
19+
## Redirects
20+
21+
Every deleted, renamed, or moved page must have a redirect added in `vercel.json`. Docusaurus is
22+
configured with `onBrokenLinks: 'throw'`, so broken internal links will fail the build.
23+
24+
## Factual accuracy
25+
26+
Do not state as fact any API behavior, parameter, or return value that you have not verified
27+
against the codebase or published reference. If you are uncertain, add a review comment or
28+
admonition noting the uncertainty. This rule applies to both human and AI-assisted contributions.
29+
30+
## Images
31+
32+
Place images in the appropriate asset folder for this product. Reference them with relative paths
33+
from the documentation page.
34+
35+
## Update rule files for structural changes
36+
37+
When a change affects the structure, naming, or conventions of a documentation area, update the
38+
corresponding `.cursor/rules/` file in the same PR. Examples of changes that require a rule update:
39+
40+
- Renaming a product or changing its branding (update the product rule file and `terminology.mdc`).
41+
- Adding, removing, or renaming top-level content folders (update `content-types.mdc` if a new
42+
folder pattern is introduced).
43+
- Changing the parameter documentation format in a reference section (update `content-types.mdc`).
44+
- Moving image storage to a different directory (update `contributor-workflow.mdc`).
45+
- Introducing new shared partials or generated-content patterns (document in the relevant rule file).
46+
47+
Keeping rule files current prevents stale guidance from producing incorrect contributions.
48+
49+
## CI linting
50+
51+
Pull requests are checked by a Vale-based linter that enforces Microsoft style, Consensys
52+
terminology, and spelling. Fix any linter warnings before requesting review. If a warning is a
53+
false positive, add the term to the Vale vocabulary file rather than rewriting valid technical
54+
language.
55+
56+
Additional CI checks:
57+
58+
- **Prettier** - run `npm run format` locally before pushing.
59+
- **Link check** - validates internal and external links.
60+
- **Build** - the Docusaurus build must pass (`onBrokenLinks: 'throw'`).
61+
62+
## Pull requests
63+
64+
- Summarize what changed and why in the PR description. Do not just list files.
65+
- Link the related issue using `fixes #<number>` when applicable.
66+
- Preview locally with `npm start` before requesting review.
67+
68+
## Cross-area links
69+
70+
See the **Links** section in `markdown-formatting.mdc`.

‎.cursor/rules/editorial-voice.mdc‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
description: Editorial voice and tone rules aligned with the Microsoft Writing Style Guide and Consensys documentation standards.
3+
globs: ["**/*.md", "**/*.mdx"]
4+
alwaysApply: false
5+
---
6+
7+
# Editorial voice
8+
9+
Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
10+
and the [Consensys documentation style guide](https://docs-template.consensys.net/contribute/style-guide).
11+
The rules below are the most actionable subset for AI-assisted editing.
12+
13+
## Voice and tone
14+
15+
- Use active voice and present tense.
16+
- Write in second person. Address the reader as "you."
17+
- Use contractions naturally ("it's," "don't"). Be informal but not sloppy.
18+
- Refer to the reader's deployment or setup as "your [thing]" (not "the [thing]" or "the user's
19+
[thing]").
20+
- Refer to the reader as "you" (not "the developer," "the user," or "users").
21+
22+
## Clarity
23+
24+
- Get to the point in the first sentence of every section. Does it answer "what," "why," and "when"?
25+
- Use short, simple sentences. Remove nonessential or redundant words.
26+
- Break up three or more paragraphs with subheadings, lists, tables, code samples, or admonitions.
27+
- Write for developers and operators who want to accomplish a task or learn a skill, not for
28+
marketing purposes.
29+
30+
## Sentence construction
31+
32+
- Lead with what's most important. Front-load keywords for scanning.
33+
- Start sentences with a verb when possible. Edit out "you can" and "there is/are" phrasing.
34+
- Use the Oxford (serial) comma in lists of three or more items (for example, "Android, iOS, and
35+
Windows").
36+
- Do not start sentences with "So," "Basically," or "Actually."
37+
38+
## Lists
39+
40+
- Include at least two items but, if possible, no more than seven.
41+
- Keep items short enough that the reader can see two or three at a glance. A couple of short
42+
paragraphs per item is acceptable, but don't exceed that length often.
43+
- Make all items consistent in structure (for example, each item is a noun or a phrase that starts
44+
with a verb).
45+
46+
## Punctuation and formatting
47+
48+
- Do not use em dashes or en dashes. Use commas, parentheses, semicolons, or rephrase the sentence.
49+
- Use only one space after periods, question marks, and colons.
50+
- Use sentence case for all headings and titles. Never use title case.
51+
- Do not end headings, subheadings, or UI titles with periods.
52+
- Use backticks for inline code, file names, and URLs referenced in prose.
53+
- Use bold for UI element names (buttons, menu items, field labels).
54+
55+
## Developer content
56+
57+
- List prerequisites before the first step. Suggest good practices (for example, "secure private
58+
keys," "protect RPC endpoints in production").
59+
- Write code samples that are readable, can be copied and pasted, and work as expected. Do not
60+
include shell prompts (for example, `user@host $`) in code blocks.
61+
- Use angle-bracket placeholders for user-supplied values (for example, `<YOUR_API_KEY>`).
62+
63+
## What to avoid
64+
65+
- No marketing language, superlatives, or promotional tone ("best-in-class," "powerful," "seamless").
66+
- No slang, figures of speech, or culturally specific idioms.
67+
- No run-on sentences.
68+
- No jargon without definition. If a term must be used, define it on first use.

‎.cursor/rules/markdown-formatting.mdc‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
description: Markdown formatting conventions for Consensys documentation sites built with Docusaurus.
3+
globs: ["**/*.md", "**/*.mdx"]
4+
alwaysApply: false
5+
---
6+
7+
# Markdown formatting
8+
9+
Follow the [Consensys Markdown formatting guide](https://docs-template.consensys.net/contribute/format-markdown)
10+
for full details. The rules below cover the most common conventions.
11+
12+
## Line length and sentence breaks
13+
14+
- Wrap lines at roughly 80 columns (per the project `.editorconfig` and `.prettierrc`).
15+
- Start each new sentence on a new line, even if the previous line is short. This makes diffs
16+
easier to review.
17+
18+
## Links
19+
20+
- Use relative file paths for links within the same documentation area (for example,
21+
`./concepts/overview.md`).
22+
- Use absolute URL paths for cross-product or cross-area links (for example,
23+
`/other-product/how-to/configure`).
24+
- Use descriptive link text. Do not use "click here" or bare URLs.
25+
26+
## Code blocks
27+
28+
- Always specify the language on fenced code blocks (` ```javascript `, ` ```bash `, etc.).
29+
- Indent code with two spaces, not four.
30+
- Write code samples that can be copied, pasted, and run as-is. Do not include shell prompts
31+
(for example, `user@host $`) or trailing comments that break execution.
32+
- Use angle-bracket placeholders for values the reader must supply
33+
(for example, `<YOUR_API_KEY>`).
34+
35+
## Tabs
36+
37+
- Use Docusaurus `<Tabs>` and `<TabItem>` components to display parallel content such as
38+
command-line syntax or configuration in different formats.
39+
- Import `Tabs` and `TabItem` from `@theme/Tabs` and `@theme/TabItem` at the top of the file.
40+
41+
## Admonitions
42+
43+
- Use Docusaurus admonitions: `:::note`, `:::tip`, `:::caution`, `:::warning`, `:::info`, and `:::danger`.
44+
- Add a custom title on the same line only when it helps scanning (for example,
45+
`:::caution important`).
46+
- For deprecated features or content, use `:::warning Deprecated`.
47+
State that the feature or content is deprecated and will be removed in a future release.
48+
- Do not nest admonitions.
49+
50+
## Tables
51+
52+
- Align table columns in the source Markdown for readability.
53+
- Use a tool like [Markdown Table Formatter](https://markdowntable.com/) if needed.
54+
55+
## Frontmatter
56+
57+
- Required: `description` (one sentence for SEO and previews).
58+
- Recommended: `keywords` (array).
59+
- `sidebar_label`: optional. Use sparingly; only when the default sidebar text (usually from the
60+
page title) would be too long or wordy for the navigation. Omit when the default is fine.
61+
- If the frontmatter contains a `title` field, do not add a separate top-level `# Heading` to
62+
avoid a duplicate H1.
63+
64+
## File and folder names
65+
66+
- Use lowercase letters and dashes only (for example, `configure-api.md`, not
67+
`configureAPI.md`).
68+
69+
## Diagrams
70+
71+
- Use [Mermaid](https://mermaid.js.org/) for diagrams where possible. Enable
72+
`@docusaurus/theme-mermaid` in `docusaurus.config.js` if it is not already active.

‎.cursor/rules/terminology.mdc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
description: Required spelling and casing for product names, industry terms, and standards referenced across this documentation site.
3+
globs: ["**/*.md", "**/*.mdx"]
4+
alwaysApply: false
5+
---
6+
7+
# Terminology
8+
9+
Use the following terms consistently. The left column is the required form. Do not use the variants
10+
listed on the right unless they appear in code, URLs, or direct quotations from a specification.
11+
12+
## General Consensys terms
13+
14+
| Required term | Do not use |
15+
|---------------|-----------------------------------------------|
16+
| Consensys | ConsenSys, consensys |
17+
| MetaMask | Metamask, metamask |
18+
| dapp | DApp, Dapp, dApp, decentralized application |
19+
| smart contract | smartcontract, smart-contract |
20+
| web3 | Web3, WEB3 (capitalize only at sentence start)|
21+
| JSON-RPC | json-rpc, Json-RPC, JSONRPC |
22+
| onchain / offchain | on-chain, off-chain |
23+
24+
## Product-specific terms
25+
26+
<!-- TODO: Add product-specific terminology for this site. -->
27+
<!-- Follow the pattern: Required term | Do not use -->
28+
29+
## Standards and specifications
30+
31+
When introducing a standard for the first time on a page, spell out the full name with the
32+
identifier in parentheses. Use the short form on subsequent references.
33+
34+
Examples:
35+
36+
- First use: "Ethereum Improvement Proposal 1559 (EIP-1559)"
37+
- Subsequent: "EIP-1559"

0 commit comments

Comments
 (0)