​

Contribution Guidelines

​

Getting Started

​

Prerequisites

• Node.js 18+
• Mintlify CLI

​

Local Development

cd docs
mintlify dev

​

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

---
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 <Frame> 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

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

​

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.

​

Navigation

• 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

​

Page Types

​

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

​

Required Sections

​

File Naming

{ordinal}-{hardfork}-{component}-{feature}.mdx

​

Components

​

Placeholder Pages

---
title: "Page Title"
description: "Brief description"
---

Coming Soon

​

Governance

​

Adding Solutions or Use Cases

1. Integrate DeFi
2. Tokenize Assets
3. Issue Stablecoins
4. Accept Payments

​

IA Changes

​

Opening a Pull Request

• Base branch: master is the default branch of base/docs. Branch from master (in your fork) and open your pull request against master.
• Page format: Create new pages as .mdx files under docs/. The Docs Style / Conformance check lints only the .mdx files under docs/ that your pull request changes, and orphan detection in scripts/validate-docs-structure.js only scans .mdx files, so a page saved as .md skips both checks.
• Snippets and excluded files: Files in docs/snippets/ and files listed in docs/.mintignore are not published pages, so page-level lint rules do not apply to them.

​

Before Submitting

1. Run the linter and fix all errors
   node scripts/lint-mdx.js
   
   With no arguments, the linter checks the .mdx files your branch changes relative to master.
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