From bee2b8f6da9a393f9d9ad656cd16603aaa02501b Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Thu, 27 Aug 2026 15:42:32 -0400 Subject: [PATCH 1/6] update: 2x2 solutions grid, remove Resources section from home page Co-Authored-By: Claude Opus 4.6 --- docs/get-started/base.mdx | 20 +------------------- docs/style.css | 2 +- 2 files changed, 2 insertions(+), 20 deletions(-) diff --git a/docs/get-started/base.mdx b/docs/get-started/base.mdx index 30402be69..4c8018cc3 100644 --- a/docs/get-started/base.mdx +++ b/docs/get-started/base.mdx @@ -7,9 +7,7 @@ mode: "wide" {/* TODO(marcomms): WIP, finalize home / Get Started positioning with Xen Baynham-Herd's team. */} Base is built by Coinbase, trusted by leading institutions, and open to all. Stablecoin issuance, payments, and compliance controls ship as native chain primitives you can use out of the box, without building or auditing your own contracts. Transactions settle in under a second, and cost less than one cent. -### Solutions - - + Add direct lending, collateralized borrowing, or a vault-based earn product. @@ -23,19 +21,3 @@ Base is built by Coinbase, trusted by leading institutions, and open to all. Sta Take instant stablecoin and agent-driven payments with low fees. - -
- ### Resources -
-
-

Funding

- Grants - Base Ecosystem Fund -
-
-

Growth

- Base Batches - Base Dashboard -
-
-
diff --git a/docs/style.css b/docs/style.css index 552f8d8b7..f79fc2301 100644 --- a/docs/style.css +++ b/docs/style.css @@ -245,7 +245,7 @@ body > div, main { .use-cases { display: grid; - grid-template-columns: repeat(3, 1fr); + grid-template-columns: repeat(2, 1fr); gap: 2rem; padding-bottom: 2rem; } From 4417e681dc021982dc594078dd5f996677bc087e Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Thu, 27 Aug 2026 15:51:57 -0400 Subject: [PATCH 2/6] update: reorder Reference section, move Troubleshooting into Transactions Co-Authored-By: Claude Opus 4.6 --- docs/docs.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 3c17275e9..57ae9b635 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -224,7 +224,8 @@ "group": "Transactions", "pages": [ "base-chain/network-information/transaction-ordering", - "base-chain/network-information/transaction-finality" + "base-chain/network-information/transaction-finality", + "base-chain/network-information/troubleshooting-transactions" ] }, "base-chain/flashblocks/faq" @@ -290,11 +291,10 @@ "base-chain/specs/reference/builder-codes/agent-developers" ] }, - "base-chain/network-information/smart-contracts", "base-chain/network-information/base-contracts", - "base-chain/specs/reference/glossary", + "base-chain/network-information/smart-contracts", "base-chain/specs/reference/configurability", - "base-chain/network-information/troubleshooting-transactions" + "base-chain/specs/reference/glossary" ] }, { From e94ae713ab01c1ffe36bb59fbe1afcae0d47f13a Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Thu, 27 Aug 2026 15:55:28 -0400 Subject: [PATCH 3/6] add: content guidelines, contribution guidelines, and icon assets Co-Authored-By: Claude Opus 4.6 --- docs/content-guidelines.mdx | 239 +++++++++++++++++++++++++++ docs/contribution-guidelines.md | 260 ++++++++++++++++++++++++++++++ docs/images/icons/assets.svg | 7 + docs/images/icons/hero-bg.svg | 9 ++ docs/images/icons/payments.svg | 6 + docs/images/icons/stablecoins.svg | 6 + docs/images/icons/trading.svg | 8 + 7 files changed, 535 insertions(+) create mode 100644 docs/content-guidelines.mdx create mode 100644 docs/contribution-guidelines.md create mode 100644 docs/images/icons/assets.svg create mode 100644 docs/images/icons/hero-bg.svg create mode 100644 docs/images/icons/payments.svg create mode 100644 docs/images/icons/stablecoins.svg create mode 100644 docs/images/icons/trading.svg diff --git a/docs/content-guidelines.mdx b/docs/content-guidelines.mdx new file mode 100644 index 000000000..8b1c5532b --- /dev/null +++ b/docs/content-guidelines.mdx @@ -0,0 +1,239 @@ +--- +title: "Content Guidelines" +description: "Writing rules, specification page structure, and changelog entry format for Base documentation." +--- + +## Writing Rules + +### Language and Style + +- Use clear, direct language appropriate for technical audiences +- Write in second person ("you") for instructions and procedures +- Use active voice over passive voice +- Employ present tense for current states, future tense for outcomes +- Avoid jargon unless necessary and define terms when first used +- Maintain consistent terminology throughout all documentation +- Keep sentences concise while providing necessary context +- Use parallel structure in lists, headings, and procedures + +### Content Organization + +- Lead with the most important information (inverted pyramid structure) +- Use progressive disclosure: basic concepts before advanced ones +- Break complex procedures into numbered steps +- Only include prerequisites and context before instructions when necessary for instructions to be understood +- Provide expected outcomes for each major step +- Use descriptive, keyword-rich headings for navigation and SEO +- Group related information logically with clear section breaks + +### User-Centered Approach + +- Focus on user goals and outcomes rather than system features +- Anticipate common questions and address them proactively +- Include troubleshooting for likely failure points +- Write for scannability with clear headings, lists, and white space +- Include verification steps to confirm success + +### Required Page Structure + +Every documentation page must begin with YAML frontmatter: + +```yaml +--- +title: "Clear, specific, keyword-rich title" +description: "Concise description explaining page purpose and value" +--- +``` + +### Code Examples + +- Every code block must have a filename or a title + - If filename, add filename after language (e.g. ` ```typescript page.tsx `) + - If title, add Title followed by the title (e.g. ` ```typescript Title example `) +- Highlight the most relevant lines of the codeblock using ` ```typescript highlight={1-2,5} ` +- Code blocks longer than 7 lines should: + - Have line numbers by adding `lines` to the first line of the codeblock + - Be marked as `expandable` by adding to the first line of the codeblock +- Use `wrap` to prevent horizontal scrolling of codeblocks +- Always include complete, runnable examples that users can copy and execute +- Show proper error handling and edge case management +- Use realistic data instead of placeholder values +- Include expected outputs and results for verification +- Add explanatory comments for complex logic +- Never include real API keys or secrets in code examples + +### API Documentation + +- Document all parameters including optional ones with clear descriptions +- Show both success and error response examples with realistic data +- Include rate limiting information with specific limits +- Provide authentication examples showing proper format +- Explain all HTTP status codes and error handling +- Cover complete request/response cycles + +### Accessibility + +- Include descriptive alt text for all images and diagrams +- Use specific, actionable link text instead of "click here" +- Ensure proper heading hierarchy starting with H2 +- Provide keyboard navigation considerations +- Use sufficient color contrast in examples and visuals +- Structure content for easy scanning with headers and lists + +### Component Selection + +| Component | Use for | +|-----------|---------| +| **Steps** | Procedures and sequential instructions | +| **Tabs** | Platform-specific content or alternative approaches | +| **CodeGroup** | Same concept in multiple programming languages or frameworks | +| **Accordions** | Progressive disclosure of information | +| **RequestExample / ResponseExample** | API endpoint documentation | +| **ParamField** | API parameters | +| **ResponseField** | API responses | +| **Expandable** | Nested object properties or hierarchical information | + +--- + +## Specification Pages + +Content structure and writing guidelines for Base Protocol specification pages — Core Primitives and Network Systems. + +### Page Types + +Every feature or subsystem in Core Primitives and Network Systems uses a combination of these page types: + +| Page type | Purpose | Example | +|-----------|---------|---------| +| **Overview / index** | What this feature is, why it exists, how the pieces fit together. Entry point for the subsystem. | B20 specification, Proofs index, Consensus index | +| **Reference page** | One page per contract, interface, or component. Exhaustive: every function, error, event, constant. | IB20, IB20Asset, IPolicyRegistry | +| **Supporting page** | Constants, errors, events, invariants, or test cases collected across the subsystem. | B20 constants and addresses, B20 errors and events | +| **Changelog summary** | Per-hardfork summary of what changed in this feature, linking out to detail entries in the Upgrades tab. | B20 changelog | + +Not every feature needs all four types. A single-page feature (e.g., network fees) can be one overview page. A multi-contract system (e.g., B20, proofs) needs the full set. + +### Page Structure + +#### Overview / Index Pages + +1. **Status note** — if the spec is tied to a specific hardfork, state which one (e.g., "This is the normative Beryl specification for B20.") +2. **Introduction** — 1–2 paragraphs: what the feature is and what problem it solves. No preamble or history. +3. **Key concepts** — the core abstractions a reader needs before diving into reference pages. Use tables for enumerations (roles, policy types, variants). Use short prose for behavioral concepts. +4. **Architecture / component map** — for multi-component systems, list the components and what each one does. Link to the individual reference pages. +5. **Cross-references** — link to related Build on Base guides ("To deploy a B20 token, see Issue Stablecoins") and the changelog summary page. + +#### Reference Pages + +1. **Title** — the contract or interface name (e.g., "IB20Asset") +2. **Description** — one sentence on what this interface does +3. **Functions** — every function, grouped logically (not alphabetically). For each: + - Solidity signature in a code block + - Parameters table: name, type, description + - Return values + - Access control (which role gates it) + - Behavioral notes (reverts, edge cases) +4. **Events** — signature and field descriptions +5. **Errors** — signature and when each is thrown + +#### Supporting Pages + +- **Constants and addresses** — table format: name, value, description. Group by contract or purpose. +- **Errors and events** — collected across the subsystem when they span multiple interfaces. Use tables with the interface they belong to. +- **Invariants and tests** — state the invariant in plain language, then the test assertion or reference to the test file. + +#### Changelog Summary Pages + +1. **Hardfork table** — list all hardforks that touched this feature, with ordinal, name, and status. +2. **Per-hardfork section** — newest first. Each section: + - Heading links to the hardfork overview in the Upgrades tab (e.g., `## [Cobalt](/base-chain/specs/upgrades/cobalt/overview)`) + - Table of changes with links to the detail entries in the Upgrades tab + - For the initial release hardfork: summary of what shipped (Added / Deprecated lists) +3. **No detail content** — the summary page links out, it doesn't duplicate. The Upgrades tab owns the migration details. + +### Writing Rules for Spec Pages + +- **Be normative, not tutorial.** Spec pages define how something works, not how to use it. "The batcher encodes L2 blocks into channels" not "To submit data, you encode blocks into channels." +- **Lead with behavior, not motivation.** Save motivation for the changelog. The spec describes the current state. +- **Code over prose.** Show the Solidity signature, then explain. Don't describe a function without showing it. +- **Tables for enumerations.** Roles, policy types, error codes, constants — always tables, never bullet lists. +- **Diffs for changes.** When documenting what changed between hardforks (in changelog entries), show before/after code, not a paragraph describing the difference. +- **One concept per section.** If a section covers two unrelated behaviors, split it. +- **Link, don't duplicate.** Reference pages link to the overview for context. The overview links to reference pages for detail. Neither copies the other. + +### Grouping Rules + +A feature gets a nested group in the sidebar (like B20, Bridging, Proofs) when it has 3+ pages. Features with 1–2 pages sit as flat entries in the parent group. + +| Core Primitives | Network Systems | +|-----------------|-----------------| +| Things developers interact with directly | Protocol internals that power the chain | +| User-facing behavior: tokens, transactions, fees, bridges | Infrastructure: batcher, derivation, execution, proofs | +| "What can I do on Base?" | "How does Base work under the hood?" | +| Audience: app developers, integrators | Audience: protocol engineers, node operators, researchers | + +--- + +## Changelog Entries + +Changelog entries follow a consistent structure inspired by improvement proposals (TIPs, EIPs). Not every section applies to every change — a node upgrade looks different from a new contract interface. Use the sections that fit; skip the rest. + +### Core Sections + +Every changelog entry should include these: + +| Section | Purpose | +|---------|---------| +| **Abstract** | One-paragraph summary: what changed, what it affects, which hardfork introduces it. | +| **Motivation** | Why this change exists — the problem, limitation, or opportunity it addresses. | +| **What Changed** | The substance of the change. Structure depends on the type of change (see below). | +| **Migration** | What developers or operators need to do. Breaking changes, deprecations, new defaults, upgrade steps. | + +### Optional Sections + +Include when relevant: + +| Section | When to include | +|---------|-----------------| +| **Alternatives considered** | Non-trivial design decisions where other approaches were evaluated. | +| **Test cases** | Key scenarios that validate the change. Reference invariant tests where applicable. | + +### Structuring "What Changed" + +The body of a changelog entry varies by change type. Use the structure that fits: + +**Contract / interface changes** (e.g., B20 updates, new precompiles): +- New or modified function signatures (Solidity code blocks) +- New errors and events +- Typed data changes (domain separators, typehashes) if applicable +- Behavioral changes — one subsection per area affected +- Show before/after diffs rather than describing changes in prose + +**Protocol / network changes** (e.g., throughput limits, fee parameters, derivation changes): +- Parameter changes (old value → new value) +- Behavioral impact on nodes, sequencers, or verifiers +- Configuration changes required + +**Node / infrastructure changes** (e.g., client upgrades, new RPC methods): +- Version requirements +- New or changed CLI flags, environment variables, config keys +- New API endpoints or methods + +**Cross-references**: Link to the canonical spec page in Base Protocol for the full current state. The changelog entry records *what changed*, not the complete specification. + +### Naming Convention + +``` +{ordinal}-{hardfork}-{component}-{feature}.mdx +``` + +| Segment | Format | Example | +|---------|--------|---------| +| Ordinal | Two-digit hardfork number | `02` (Cobalt) | +| Hardfork | Lowercase hardfork name | `cobalt` | +| Component | Lowercase component name | `b20asset`, `policyregistry`, `node` | +| Feature | Lowercase kebab-case feature slug | `multiplier`, `composite-policy` | + +Examples: +- `02-cobalt-b20asset-multiplier.mdx` +- `02-cobalt-b20-seize.mdx` +- `02-cobalt-policyregistry-composite-policy.mdx` diff --git a/docs/contribution-guidelines.md b/docs/contribution-guidelines.md new file mode 100644 index 000000000..cc3ddd88c --- /dev/null +++ b/docs/contribution-guidelines.md @@ -0,0 +1,260 @@ +# Contribution Guidelines + +How to contribute to Base documentation. This guide covers setup, writing standards, page placement, and the review process. + +--- + +## Getting Started + +### Prerequisites + +- Node.js 18+ +- [Mintlify CLI](https://mintlify.com/docs/development) + +### Local Development + +```bash +cd docs +mintlify dev +``` + +The site runs at `http://localhost:3000`. Changes hot-reload automatically. + +### Repository Structure + +``` +docs/ +├── get-started/ # Intro, quickstarts +├── base-chain/ # Network, nodes, tools +├── base-account/ # Smart Wallet SDK +├── ai-agents/ # Agent development +├── apps/ # Apps on Base (MiniKit, guides) +├── onchainkit/ # React components (versioned) +├── images/ # Assets by topic +├── snippets/ # Reusable MDX components +└── docs.json # Navigation config +``` + +--- + +## Writing Standards + +### Every Page Requires Frontmatter + +```yaml +--- +title: "Clear, Keyword-Rich Title" +description: "Concise description explaining the page's purpose and value." +--- +``` + +- **Title**: Use title case. Capitalize all words except short conjunctions and articles (e.g., "Integrate an Earn Product"). +- **Description**: Mintlify renders this as a visible subtitle below the page title. Write it for humans, not just SEO. + +### Language and Style + +- American English +- Second person ("you") for instructions +- Active voice over passive voice +- Present tense for current states, future tense for outcomes +- Define jargon when first used +- Parallel structure in lists and headings +- Action-oriented names when possible — "Integrate DeFi" not "DeFi Integration" +- Enterprise tone for financial use cases — "Integrate Borrowing" not "Get a Loan" + +### Content Organization + +- Lead with the most important information (inverted pyramid) +- Progressive disclosure: basic concepts before advanced ones +- Break complex procedures into numbered steps +- Use descriptive, keyword-rich headings +- Group related information with clear section breaks +- Focus on user goals rather than system features +- Include troubleshooting for likely failure points + +### Code Examples + +- Every code block must have a filename or title after the language tag +- Highlight key lines: ` ```typescript highlight={1-2,5} ` +- Code blocks longer than 7 lines: add `lines` for line numbers and `expandable` +- Use `wrap` to prevent horizontal scrolling +- Always include complete, runnable examples +- Use realistic data — no `foo`, `bar`, or `example.com` +- Never include real API keys or secrets + +### Images + +- Wrap in `` with a descriptive `alt` attribute +- Place image files in `docs/images/` organized by topic + +### Accessibility + +- Descriptive alt text for all images +- Specific link text — never "click here" +- Proper heading hierarchy starting with H2 +- Sufficient color contrast in examples + +--- + +## Where to Put New Pages + +Pages are organized across six tabs. Use this decision tree: + +1. **Is it a protocol specification?** → Specifications +2. **Is it a hardfork change or migration guide?** → Upgrades +3. **Is it SDK or API documentation?** → SDKs & APIs +4. **Does it teach how to build a specific product?** → Build on Base +5. **Is it about connecting infrastructure to Base?** → Specifications (Base Protocol landing) +6. **Is it an entry point for new developers?** → Get Started + +### Tab Overview + +| Tab | Audience | Contains | +|-----|----------|----------| +| **Get Started** | First-time visitors | Quickstarts, solution overviews, funding, coding agents | +| **Build on Base** | Developers building products | Step-by-step implementation guides by use case | +| **Specifications** | Protocol engineers, integrators | Core Primitives, Network Systems, node operations, reference | +| **SDKs & APIs** | Developers using SDKs/APIs | Base Account SDK, Base Chain API, quickstarts | +| **Upgrades** | Node operators, integrators | Hardfork overviews, changelog entries, migration guides | + +### Rules + +- A page appears in exactly one tab. If it fits two, prefer the more specific one. +- Hardfork-specific content always goes in Upgrades, even if it relates to a feature documented elsewhere. +- Get Started pages are entry ramps — they link to deeper sections, never duplicate content. +- Concept explainers that support integration go in Specifications > Reference, not in Build on Base. + +For the full tab and section breakdown, see [ia-guidelines.md](ia-guidelines.md). + +--- + +## Navigation + +Edit `docs/docs.json` to add or remove pages from the sidebar. + +- **Adding a page**: Add the path to the appropriate group in `docs.json`. +- **Removing a page**: Always add a redirect in `docs.json` before deleting. Never remove a URL without a redirect. +- **Reordering**: Items appear in the sidebar in the order listed in `docs.json`. +- **Grouping**: A feature gets its own nested nav group when it has 3+ pages. Features with 1–2 pages sit as flat entries. + +--- + +## Specification Pages + +Spec pages in Core Primitives and Network Systems follow a specific structure. See [content-guidelines.md](../content-guidelines.md) for the full reference. + +### Page Types + +| Type | Purpose | +|------|---------| +| **Overview / index** | What the feature is, why it exists, how pieces fit together | +| **Reference page** | One page per contract or interface — every function, error, event | +| **Supporting page** | Constants, errors, events, invariants collected across a subsystem | +| **Changelog summary** | Per-hardfork summary linking to detail entries in Upgrades | + +### Writing Rules + +- **Be normative, not tutorial.** Spec pages define how something works, not how to use it. +- **Code over prose.** Show the Solidity signature, then explain. +- **Tables for enumerations.** Roles, policy types, error codes — always tables, never bullets. +- **Link, don't duplicate.** Reference pages link to the overview for context and vice versa. + +--- + +## Changelog Entries + +Upgrade pages follow a structure inspired by improvement proposals (TIPs, EIPs). See [content-guidelines.md](../content-guidelines.md) for the full template. + +### Required Sections + +| Section | Purpose | +|---------|---------| +| **Abstract** | One-paragraph summary: what changed, what it affects, which hardfork | +| **Motivation** | Why this change exists | +| **What Changed** | The substance — show before/after diffs for contract changes | +| **Migration** | What developers or operators need to do | + +### File Naming + +``` +{ordinal}-{hardfork}-{component}-{feature}.mdx +``` + +Examples: `02-cobalt-b20asset-multiplier.mdx`, `02-cobalt-policyregistry-composite-policy.mdx` + +--- + +## Components + +Use the right Mintlify component for the content type: + +| Component | Use for | +|-----------|---------| +| **Steps** | Sequential procedures | +| **Tabs** | Platform-specific or alternative approaches | +| **CodeGroup** | Same concept in multiple languages | +| **Accordions** | Progressive disclosure | +| **Cards / CardGroup** | Navigation grids linking to related pages | +| **ParamField / ResponseField** | API parameter and response documentation | +| **Expandable** | Nested object properties | + +See [mintlify-reference.md](../mintlify-reference.md) for full syntax examples. + +--- + +## Placeholder Pages + +New pages without content use this format: + +```yaml +--- +title: "Page Title" +description: "Brief description" +--- + +Coming Soon +``` + +--- + +## Governance + +### Adding Solutions or Use Cases + +Before adding a new solution to Get Started or Build on Base, or renaming an existing section, you need approval from **Eric Brown** and **Mind Apivessa**. Mind Apivessa is responsible for getting approvals from BD and GTM. + +Solutions are ordered by prominence. Current order: + +1. Integrate DeFi +2. Tokenize Assets +3. Issue Stablecoins +4. Accept Payments + +### IA Changes + +Structural changes to the information architecture — adding tabs, renaming sections, moving pages between tabs — should be discussed before implementation. Reference [ia-guidelines.md](ia-guidelines.md) for the current structure and decision log. + +--- + +## Before Submitting + +1. **Run the linter** and fix all errors + ```bash + node scripts/lint-mdx.js + ``` +2. **Add redirects** for any removed or moved pages +3. **Verify links** work — broken links block deployment +4. **Preview locally** with `mintlify dev` to check rendering +5. **Check frontmatter** — every page needs `title` and `description` +6. **Title case** — all headings and page titles use title case + +--- + +## Reference Files + +| File | Purpose | +|------|---------| +| [content-guidelines.md](../content-guidelines.md) | Writing rules, spec page structure, changelog format | +| [ia-guidelines.md](ia-guidelines.md) | What belongs in each tab and section | +| [mintlify-reference.md](../mintlify-reference.md) | Mintlify component syntax | +| [scripts/README.md](../scripts/README.md) | Linter usage | diff --git a/docs/images/icons/assets.svg b/docs/images/icons/assets.svg new file mode 100644 index 000000000..f3efbcb02 --- /dev/null +++ b/docs/images/icons/assets.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/docs/images/icons/hero-bg.svg b/docs/images/icons/hero-bg.svg new file mode 100644 index 000000000..b66964785 --- /dev/null +++ b/docs/images/icons/hero-bg.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/docs/images/icons/payments.svg b/docs/images/icons/payments.svg new file mode 100644 index 000000000..38bfe7ea8 --- /dev/null +++ b/docs/images/icons/payments.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/images/icons/stablecoins.svg b/docs/images/icons/stablecoins.svg new file mode 100644 index 000000000..a8e4ae45d --- /dev/null +++ b/docs/images/icons/stablecoins.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/images/icons/trading.svg b/docs/images/icons/trading.svg new file mode 100644 index 000000000..3883a8453 --- /dev/null +++ b/docs/images/icons/trading.svg @@ -0,0 +1,8 @@ + + + + + + + + From 5d6c28d37a2428f7f6466b1a5004b49feec4ed49 Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Thu, 27 Aug 2026 15:59:43 -0400 Subject: [PATCH 4/6] fix: remove orphan content-guidelines.mdx from docs/ Co-Authored-By: Claude Opus 4.6 --- docs/content-guidelines.mdx | 239 ------------------------------------ 1 file changed, 239 deletions(-) delete mode 100644 docs/content-guidelines.mdx diff --git a/docs/content-guidelines.mdx b/docs/content-guidelines.mdx deleted file mode 100644 index 8b1c5532b..000000000 --- a/docs/content-guidelines.mdx +++ /dev/null @@ -1,239 +0,0 @@ ---- -title: "Content Guidelines" -description: "Writing rules, specification page structure, and changelog entry format for Base documentation." ---- - -## Writing Rules - -### Language and Style - -- Use clear, direct language appropriate for technical audiences -- Write in second person ("you") for instructions and procedures -- Use active voice over passive voice -- Employ present tense for current states, future tense for outcomes -- Avoid jargon unless necessary and define terms when first used -- Maintain consistent terminology throughout all documentation -- Keep sentences concise while providing necessary context -- Use parallel structure in lists, headings, and procedures - -### Content Organization - -- Lead with the most important information (inverted pyramid structure) -- Use progressive disclosure: basic concepts before advanced ones -- Break complex procedures into numbered steps -- Only include prerequisites and context before instructions when necessary for instructions to be understood -- Provide expected outcomes for each major step -- Use descriptive, keyword-rich headings for navigation and SEO -- Group related information logically with clear section breaks - -### User-Centered Approach - -- Focus on user goals and outcomes rather than system features -- Anticipate common questions and address them proactively -- Include troubleshooting for likely failure points -- Write for scannability with clear headings, lists, and white space -- Include verification steps to confirm success - -### Required Page Structure - -Every documentation page must begin with YAML frontmatter: - -```yaml ---- -title: "Clear, specific, keyword-rich title" -description: "Concise description explaining page purpose and value" ---- -``` - -### Code Examples - -- Every code block must have a filename or a title - - If filename, add filename after language (e.g. ` ```typescript page.tsx `) - - If title, add Title followed by the title (e.g. ` ```typescript Title example `) -- Highlight the most relevant lines of the codeblock using ` ```typescript highlight={1-2,5} ` -- Code blocks longer than 7 lines should: - - Have line numbers by adding `lines` to the first line of the codeblock - - Be marked as `expandable` by adding to the first line of the codeblock -- Use `wrap` to prevent horizontal scrolling of codeblocks -- Always include complete, runnable examples that users can copy and execute -- Show proper error handling and edge case management -- Use realistic data instead of placeholder values -- Include expected outputs and results for verification -- Add explanatory comments for complex logic -- Never include real API keys or secrets in code examples - -### API Documentation - -- Document all parameters including optional ones with clear descriptions -- Show both success and error response examples with realistic data -- Include rate limiting information with specific limits -- Provide authentication examples showing proper format -- Explain all HTTP status codes and error handling -- Cover complete request/response cycles - -### Accessibility - -- Include descriptive alt text for all images and diagrams -- Use specific, actionable link text instead of "click here" -- Ensure proper heading hierarchy starting with H2 -- Provide keyboard navigation considerations -- Use sufficient color contrast in examples and visuals -- Structure content for easy scanning with headers and lists - -### Component Selection - -| Component | Use for | -|-----------|---------| -| **Steps** | Procedures and sequential instructions | -| **Tabs** | Platform-specific content or alternative approaches | -| **CodeGroup** | Same concept in multiple programming languages or frameworks | -| **Accordions** | Progressive disclosure of information | -| **RequestExample / ResponseExample** | API endpoint documentation | -| **ParamField** | API parameters | -| **ResponseField** | API responses | -| **Expandable** | Nested object properties or hierarchical information | - ---- - -## Specification Pages - -Content structure and writing guidelines for Base Protocol specification pages — Core Primitives and Network Systems. - -### Page Types - -Every feature or subsystem in Core Primitives and Network Systems uses a combination of these page types: - -| Page type | Purpose | Example | -|-----------|---------|---------| -| **Overview / index** | What this feature is, why it exists, how the pieces fit together. Entry point for the subsystem. | B20 specification, Proofs index, Consensus index | -| **Reference page** | One page per contract, interface, or component. Exhaustive: every function, error, event, constant. | IB20, IB20Asset, IPolicyRegistry | -| **Supporting page** | Constants, errors, events, invariants, or test cases collected across the subsystem. | B20 constants and addresses, B20 errors and events | -| **Changelog summary** | Per-hardfork summary of what changed in this feature, linking out to detail entries in the Upgrades tab. | B20 changelog | - -Not every feature needs all four types. A single-page feature (e.g., network fees) can be one overview page. A multi-contract system (e.g., B20, proofs) needs the full set. - -### Page Structure - -#### Overview / Index Pages - -1. **Status note** — if the spec is tied to a specific hardfork, state which one (e.g., "This is the normative Beryl specification for B20.") -2. **Introduction** — 1–2 paragraphs: what the feature is and what problem it solves. No preamble or history. -3. **Key concepts** — the core abstractions a reader needs before diving into reference pages. Use tables for enumerations (roles, policy types, variants). Use short prose for behavioral concepts. -4. **Architecture / component map** — for multi-component systems, list the components and what each one does. Link to the individual reference pages. -5. **Cross-references** — link to related Build on Base guides ("To deploy a B20 token, see Issue Stablecoins") and the changelog summary page. - -#### Reference Pages - -1. **Title** — the contract or interface name (e.g., "IB20Asset") -2. **Description** — one sentence on what this interface does -3. **Functions** — every function, grouped logically (not alphabetically). For each: - - Solidity signature in a code block - - Parameters table: name, type, description - - Return values - - Access control (which role gates it) - - Behavioral notes (reverts, edge cases) -4. **Events** — signature and field descriptions -5. **Errors** — signature and when each is thrown - -#### Supporting Pages - -- **Constants and addresses** — table format: name, value, description. Group by contract or purpose. -- **Errors and events** — collected across the subsystem when they span multiple interfaces. Use tables with the interface they belong to. -- **Invariants and tests** — state the invariant in plain language, then the test assertion or reference to the test file. - -#### Changelog Summary Pages - -1. **Hardfork table** — list all hardforks that touched this feature, with ordinal, name, and status. -2. **Per-hardfork section** — newest first. Each section: - - Heading links to the hardfork overview in the Upgrades tab (e.g., `## [Cobalt](/base-chain/specs/upgrades/cobalt/overview)`) - - Table of changes with links to the detail entries in the Upgrades tab - - For the initial release hardfork: summary of what shipped (Added / Deprecated lists) -3. **No detail content** — the summary page links out, it doesn't duplicate. The Upgrades tab owns the migration details. - -### Writing Rules for Spec Pages - -- **Be normative, not tutorial.** Spec pages define how something works, not how to use it. "The batcher encodes L2 blocks into channels" not "To submit data, you encode blocks into channels." -- **Lead with behavior, not motivation.** Save motivation for the changelog. The spec describes the current state. -- **Code over prose.** Show the Solidity signature, then explain. Don't describe a function without showing it. -- **Tables for enumerations.** Roles, policy types, error codes, constants — always tables, never bullet lists. -- **Diffs for changes.** When documenting what changed between hardforks (in changelog entries), show before/after code, not a paragraph describing the difference. -- **One concept per section.** If a section covers two unrelated behaviors, split it. -- **Link, don't duplicate.** Reference pages link to the overview for context. The overview links to reference pages for detail. Neither copies the other. - -### Grouping Rules - -A feature gets a nested group in the sidebar (like B20, Bridging, Proofs) when it has 3+ pages. Features with 1–2 pages sit as flat entries in the parent group. - -| Core Primitives | Network Systems | -|-----------------|-----------------| -| Things developers interact with directly | Protocol internals that power the chain | -| User-facing behavior: tokens, transactions, fees, bridges | Infrastructure: batcher, derivation, execution, proofs | -| "What can I do on Base?" | "How does Base work under the hood?" | -| Audience: app developers, integrators | Audience: protocol engineers, node operators, researchers | - ---- - -## Changelog Entries - -Changelog entries follow a consistent structure inspired by improvement proposals (TIPs, EIPs). Not every section applies to every change — a node upgrade looks different from a new contract interface. Use the sections that fit; skip the rest. - -### Core Sections - -Every changelog entry should include these: - -| Section | Purpose | -|---------|---------| -| **Abstract** | One-paragraph summary: what changed, what it affects, which hardfork introduces it. | -| **Motivation** | Why this change exists — the problem, limitation, or opportunity it addresses. | -| **What Changed** | The substance of the change. Structure depends on the type of change (see below). | -| **Migration** | What developers or operators need to do. Breaking changes, deprecations, new defaults, upgrade steps. | - -### Optional Sections - -Include when relevant: - -| Section | When to include | -|---------|-----------------| -| **Alternatives considered** | Non-trivial design decisions where other approaches were evaluated. | -| **Test cases** | Key scenarios that validate the change. Reference invariant tests where applicable. | - -### Structuring "What Changed" - -The body of a changelog entry varies by change type. Use the structure that fits: - -**Contract / interface changes** (e.g., B20 updates, new precompiles): -- New or modified function signatures (Solidity code blocks) -- New errors and events -- Typed data changes (domain separators, typehashes) if applicable -- Behavioral changes — one subsection per area affected -- Show before/after diffs rather than describing changes in prose - -**Protocol / network changes** (e.g., throughput limits, fee parameters, derivation changes): -- Parameter changes (old value → new value) -- Behavioral impact on nodes, sequencers, or verifiers -- Configuration changes required - -**Node / infrastructure changes** (e.g., client upgrades, new RPC methods): -- Version requirements -- New or changed CLI flags, environment variables, config keys -- New API endpoints or methods - -**Cross-references**: Link to the canonical spec page in Base Protocol for the full current state. The changelog entry records *what changed*, not the complete specification. - -### Naming Convention - -``` -{ordinal}-{hardfork}-{component}-{feature}.mdx -``` - -| Segment | Format | Example | -|---------|--------|---------| -| Ordinal | Two-digit hardfork number | `02` (Cobalt) | -| Hardfork | Lowercase hardfork name | `cobalt` | -| Component | Lowercase component name | `b20asset`, `policyregistry`, `node` | -| Feature | Lowercase kebab-case feature slug | `multiplier`, `composite-policy` | - -Examples: -- `02-cobalt-b20asset-multiplier.mdx` -- `02-cobalt-b20-seize.mdx` -- `02-cobalt-policyregistry-composite-policy.mdx` From a74853d823a4559cb083924dea7caeb6748cc542 Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Thu, 27 Aug 2026 16:06:09 -0400 Subject: [PATCH 5/6] chore: move content-guidelines and mintlify-reference into docs/ Co-Authored-By: Claude Opus 4.6 --- claude.md | 6 +++--- content-guidelines.md => docs/content-guidelines.md | 0 mintlify-reference.md => docs/mintlify-reference.md | 0 3 files changed, 3 insertions(+), 3 deletions(-) rename content-guidelines.md => docs/content-guidelines.md (100%) rename mintlify-reference.md => docs/mintlify-reference.md (100%) diff --git a/claude.md b/claude.md index 168ad1851..7c68d2966 100644 --- a/claude.md +++ b/claude.md @@ -41,7 +41,7 @@ description: "Value description" **Code blocks**: Always specify language. Add filename or title. Use `highlight={}` for emphasis. -**Components**: See [mintlify-reference.md](mintlify-reference.md) for syntax. +**Components**: See [mintlify-reference.md](docs/mintlify-reference.md) for syntax. **Images**: Wrap in ``, include `alt` attribute. @@ -53,9 +53,9 @@ Edit `docs.json` to add/remove pages. Add redirects when removing pages. | File | Purpose | |------|---------| -| [content-guidelines.md](content-guidelines.md) | Writing rules, spec page structure, changelog format | +| [content-guidelines.md](docs/content-guidelines.md) | Writing rules, spec page structure, changelog format | | [docs/ia-guidelines.md](docs/ia-guidelines.md) | What belongs in each tab and section | -| [mintlify-reference.md](mintlify-reference.md) | Component syntax | +| [mintlify-reference.md](docs/mintlify-reference.md) | Component syntax | | [scripts/README.md](scripts/README.md) | Linter usage | ## Before Committing diff --git a/content-guidelines.md b/docs/content-guidelines.md similarity index 100% rename from content-guidelines.md rename to docs/content-guidelines.md diff --git a/mintlify-reference.md b/docs/mintlify-reference.md similarity index 100% rename from mintlify-reference.md rename to docs/mintlify-reference.md From d8cc43145ba4af24a87f25440c05d88013e9cc36 Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Thu, 27 Aug 2026 16:09:57 -0400 Subject: [PATCH 6/6] chore: remove icons directory for now Co-Authored-By: Claude Opus 4.6 --- docs/images/icons/assets.svg | 7 ------- docs/images/icons/hero-bg.svg | 9 --------- docs/images/icons/payments.svg | 6 ------ docs/images/icons/stablecoins.svg | 6 ------ docs/images/icons/trading.svg | 8 -------- 5 files changed, 36 deletions(-) delete mode 100644 docs/images/icons/assets.svg delete mode 100644 docs/images/icons/hero-bg.svg delete mode 100644 docs/images/icons/payments.svg delete mode 100644 docs/images/icons/stablecoins.svg delete mode 100644 docs/images/icons/trading.svg diff --git a/docs/images/icons/assets.svg b/docs/images/icons/assets.svg deleted file mode 100644 index f3efbcb02..000000000 --- a/docs/images/icons/assets.svg +++ /dev/null @@ -1,7 +0,0 @@ - - - - - - - diff --git a/docs/images/icons/hero-bg.svg b/docs/images/icons/hero-bg.svg deleted file mode 100644 index b66964785..000000000 --- a/docs/images/icons/hero-bg.svg +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - diff --git a/docs/images/icons/payments.svg b/docs/images/icons/payments.svg deleted file mode 100644 index 38bfe7ea8..000000000 --- a/docs/images/icons/payments.svg +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/docs/images/icons/stablecoins.svg b/docs/images/icons/stablecoins.svg deleted file mode 100644 index a8e4ae45d..000000000 --- a/docs/images/icons/stablecoins.svg +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/docs/images/icons/trading.svg b/docs/images/icons/trading.svg deleted file mode 100644 index 3883a8453..000000000 --- a/docs/images/icons/trading.svg +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - -