From 7a2edcfd84ce9aee8e6eef59880dcabc0bb7b794 Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Fri, 28 Aug 2026 16:48:48 -0400 Subject: [PATCH 1/3] docs: reorganize Specifications tab by topic, consolidate bridging sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace Core Primitives and Network Systems with topic-based groups (B20, Bridging, Transactions, Flashblocks, Consensus, Execution, Proofs) so developers navigate by subject instead of abstraction level. Consolidate the two duplicate Bridging groups into one. Dissolve the bridging-and-withdrawals overview page, moving its content into the deposits and withdrawals spec pages as accessible intro sections. Move ecosystem bridges route picker to Get Started → Quickstart. Co-Authored-By: Claude Opus 4.6 --- docs/base-chain/overview.mdx | 33 ++----- .../specs/protocol/bridging/bridges.mdx | 13 +-- .../specs/protocol/bridging/deposits.mdx | 8 +- .../specs/protocol/bridging/withdrawals.mdx | 14 ++- docs/content-guidelines.md | 11 +-- docs/docs.json | 57 +++++------ docs/ia-guidelines.md | 97 +++++++++++++------ 7 files changed, 130 insertions(+), 103 deletions(-) diff --git a/docs/base-chain/overview.mdx b/docs/base-chain/overview.mdx index 40bdfbc15..08408eb1c 100644 --- a/docs/base-chain/overview.mdx +++ b/docs/base-chain/overview.mdx @@ -1,48 +1,32 @@ --- title: "Overview" -description: "Base protocol specifications, core primitives, and network systems." +description: "Base protocol specifications — tokens, bridging, transactions, consensus, execution, and proofs." --- -Technical specifications for how Base works at the chain level. Core Primitives covers what developers interact with directly — tokens, accounts, bridging, fees, and transactions. Network Systems covers protocol internals — the batcher, consensus, execution, and proof system. - -### Core Primitives +Technical specifications for how Base works at the chain level, organized by topic from user-facing primitives to protocol internals. Native token standard with compliance, memos, and supply controls. - + Smart accounts that send ordinary transactions with no bundlers or relays. - Move ETH, stablecoins, and tokens to and from Base. - - - L2 execution fees, L1 security fees, and cost-saving strategies. + Move assets to and from Base — ecosystem bridges, Solana bridge, and protocol specs. - - How transactions are ordered by priority fee and arrival time. - - - Confirmation stages from unsafe through finalized. + + Ordering, finality, fees, throughput, and troubleshooting. Sub-second block building, WebSocket data, and RPC usage. - - -### Network Systems - - - + Rollup architecture, core components, and user flows. Posting L2 sequencer data to L1 for data availability. - - Cross-domain ETH and ERC-20 transfers between L1 and L2. - L2 block derivation, P2P networking, and RPC specification. @@ -52,7 +36,4 @@ Technical specifications for how Base works at the chain level. Core Primitives Multi-proof checkpoint verification with TEE and ZK provers. - - Gas limits and throughput-related network parameters. - \ No newline at end of file diff --git a/docs/base-chain/specs/protocol/bridging/bridges.mdx b/docs/base-chain/specs/protocol/bridging/bridges.mdx index cbec5debc..6d323760a 100644 --- a/docs/base-chain/specs/protocol/bridging/bridges.mdx +++ b/docs/base-chain/specs/protocol/bridging/bridges.mdx @@ -1,8 +1,12 @@ --- title: "Standard Bridges" -description: "Specification of the standard bridges enabling cross-domain ETH and ERC20 token transfers between L1 and L2 on Base." +description: "Specification of the standard bridge contracts enabling cross-domain ETH and ERC-20 token transfers between L1 and L2 on Base." --- +The standard bridges support cross-domain ETH and ERC-20 transfers between Ethereum (L1) and Base (L2). They are built on top of the [cross-domain messenger contracts](/base-chain/specs/protocol/bridging/messengers) and provide a standard interface for moving tokens between domains. + +For the underlying transaction mechanisms, see [Deposits](/base-chain/specs/protocol/bridging/deposits) and [Withdrawals](/base-chain/specs/protocol/bridging/withdrawals). + ## Overview The standard bridges are responsible for allowing cross domain @@ -35,13 +39,6 @@ interface StandardBridge { } ``` -## Token Depositing - -The `bridgeERC20` function is used to send a token from one domain to another -domain. An `OptimismMintableERC20` token contract must exist on the remote -domain to be able to deposit tokens to that domain. One of these tokens can be -deployed using the `OptimismMintableERC20Factory` contract. - ## Upgradability Both the L1 and L2 standard bridges should be behind upgradable proxies. diff --git a/docs/base-chain/specs/protocol/bridging/deposits.mdx b/docs/base-chain/specs/protocol/bridging/deposits.mdx index ef7721f07..77aefb8cc 100644 --- a/docs/base-chain/specs/protocol/bridging/deposits.mdx +++ b/docs/base-chain/specs/protocol/bridging/deposits.mdx @@ -1,6 +1,6 @@ --- title: "Deposits" -description: "Specification of the deposit mechanism for Base, detailing how L1 transactions are converted into L2 deposit transactions." +description: "How deposits work on Base — from user experience to the protocol-level deposit transaction type and guaranteed gas market." --- [g-transaction-type]: ../../reference/glossary#transaction-type @@ -12,6 +12,12 @@ description: "Specification of the deposit mechanism for Base, detailing how L1 [g-eoa]: ../../reference/glossary#eoa [g-exec-engine]: ../../reference/glossary#execution-engine +A deposit is a transaction initiated outside Base that becomes a transaction on Base. For Ethereum deposits, the L1 transaction emits data that Base nodes use to derive a corresponding L2 deposit transaction. + +Deposit transactions are included as part of the protocol. They do not use the same signature, nonce, or fee fields as ordinary L2 transactions because they are authorized by the L1 deposit event and pay for L2 gas on L1. For most users, the practical result is simple: after the source-chain transaction is confirmed and processed, the asset or message appears on Base. + +For available bridge routes, see [Bridge to Base](/base-chain/network-information/ecosystem-bridges). + ## Overview [Deposited transactions][g-deposited], also known as [deposits][g-deposits] are transactions which diff --git a/docs/base-chain/specs/protocol/bridging/withdrawals.mdx b/docs/base-chain/specs/protocol/bridging/withdrawals.mdx index e8ecae718..5cce34e27 100644 --- a/docs/base-chain/specs/protocol/bridging/withdrawals.mdx +++ b/docs/base-chain/specs/protocol/bridging/withdrawals.mdx @@ -1,6 +1,6 @@ --- title: "Withdrawals" -description: "Specification of the withdrawal mechanism for Base, describing how L2 state is proven on L1 and funds are released from the bridge." +description: "How withdrawals work on Base — the standard 3-step flow, the 7-day challenge period, faster options, and the full protocol specification." --- [g-deposits]: ../../reference/glossary#deposits @@ -8,6 +8,18 @@ description: "Specification of the withdrawal mechanism for Base, describing how [g-relayer]: ../../reference/glossary#withdrawals [g-execution-engine]: ../../reference/glossary#execution-engine +A standard withdrawal is a cross-domain transaction initiated on Base and finalized on Ethereum. Standard withdrawals can transfer ETH, bridge supported ERC-20 tokens, or send a message from Base to an L1 contract. The flow has three stages: + +1. **Initiate on Base:** the withdrawal transaction is sent on Base. This records the withdrawal message in the `L2ToL1MessagePasser` contract. +2. **Prove on Ethereum:** after the relevant Base state has been posted to Ethereum, anyone can submit a proof to the `OptimismPortal` contract showing that the withdrawal message exists on Base. +3. **Finalize on Ethereum:** after the 7-day challenge period has passed, anyone can finalize the withdrawal on Ethereum. Finalization releases the assets or relays the message to the target contract. + + +Standard withdrawals to Ethereum must wait 7 days before they can be finalized. Base uses fault proofs to secure withdrawals — the challenge period gives network participants time to dispute an invalid output root before withdrawals that depend on it can be finalized. See [Transaction Finality](/base-chain/network-information/transaction-finality#finality-for-withdrawal-transactions) for how withdrawal finality differs from ordinary Base transaction finality. + + +Some bridge providers offer faster withdrawals by using liquidity, relayers, or market makers to give users funds before the standard withdrawal has fully finalized. See [Bridge to Base](/base-chain/network-information/ecosystem-bridges) for available routes. + ## Overview [Withdrawals][g-withdrawal] are cross domain transactions which are initiated on L2, and finalized by a transaction diff --git a/docs/content-guidelines.md b/docs/content-guidelines.md index 6adcf3dfa..0af0847fc 100644 --- a/docs/content-guidelines.md +++ b/docs/content-guidelines.md @@ -95,11 +95,11 @@ description: "Concise description explaining page purpose and value" ## Specification Pages -Content structure and writing guidelines for Base Protocol specification pages — Core Primitives and Network Systems. +Content structure and writing guidelines for Specifications pages. ### Page Types -Every feature or subsystem in Core Primitives and Network Systems uses a combination of these page types: +Every feature or subsystem in the Specifications tab uses a combination of these page types: | Page type | Purpose | Example | |-----------|---------|---------| @@ -162,12 +162,7 @@ Not every feature needs all four types. A single-page feature (e.g., network fee 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 | +Content is organized by topic (B20, Bridging, Transactions, Consensus, Execution, Proofs, etc.), not by abstraction level. Each topic group flows from user-facing overview to deep protocol spec. A feature gets a nested group in the sidebar when it has 3+ pages; features with 1–2 pages sit as flat entries or single-page groups. --- diff --git a/docs/docs.json b/docs/docs.json index 57ae9b635..1380ae030 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -43,7 +43,8 @@ "get-started/base", "get-started/connect-to-base", "get-started/get-funds", - "get-started/make-a-transaction" + "get-started/make-a-transaction", + "base-chain/network-information/ecosystem-bridges" ] }, { @@ -175,13 +176,6 @@ "group": "Specifications", "pages": [ "base-chain/overview", - "base-chain/quickstart/connecting-to-base", - "base-chain/network-information/network-faucets" - ] - }, - { - "group": "Core Primitives", - "pages": [ { "group": "B20", "pages": [ @@ -214,36 +208,40 @@ { "group": "Bridging", "pages": [ - "base-chain/network-information/ecosystem-bridges", - "base-chain/network-information/base-solana-bridge", - "base-chain/network-information/bridging-and-withdrawals" + "base-chain/specs/protocol/bridging/bridges", + "base-chain/specs/protocol/bridging/deposits", + "base-chain/specs/protocol/bridging/withdrawals", + "base-chain/specs/protocol/bridging/messengers", + "base-chain/network-information/base-solana-bridge" ] }, - "base-chain/network-information/network-fees", { "group": "Transactions", "pages": [ "base-chain/network-information/transaction-ordering", "base-chain/network-information/transaction-finality", + "base-chain/network-information/network-fees", + "base-chain/network-information/throughput-and-limits", "base-chain/network-information/troubleshooting-transactions" ] }, - "base-chain/flashblocks/faq" - ] - }, - { - "group": "Network Systems", - "pages": [ - "base-chain/specs/overview", - "base-chain/specs/protocol/overview", - "base-chain/specs/protocol/batcher", { - "group": "Bridging", + "group": "Flashblocks", "pages": [ - "base-chain/specs/protocol/bridging/bridges", - "base-chain/specs/protocol/bridging/deposits", - "base-chain/specs/protocol/bridging/messengers", - "base-chain/specs/protocol/bridging/withdrawals" + "base-chain/flashblocks/faq" + ] + }, + { + "group": "Protocol Overview", + "pages": [ + "base-chain/specs/overview", + "base-chain/specs/protocol/overview" + ] + }, + { + "group": "Batcher", + "pages": [ + "base-chain/specs/protocol/batcher" ] }, { @@ -275,8 +273,7 @@ "base-chain/specs/protocol/proofs/zk-prover", "base-chain/specs/protocol/proofs/contracts" ] - }, - "base-chain/network-information/throughput-and-limits" + } ] }, { @@ -867,6 +864,10 @@ ] }, "redirects": [ + { + "source": "/base-chain/network-information/bridging-and-withdrawals", + "destination": "/base-chain/specs/protocol/bridging/withdrawals" + }, { "source": "/base-account", "destination": "/sdks/base-account/overview" diff --git a/docs/ia-guidelines.md b/docs/ia-guidelines.md index 25e0f9de1..86baf11ee 100644 --- a/docs/ia-guidelines.md +++ b/docs/ia-guidelines.md @@ -46,7 +46,7 @@ What belongs in each navigation tab and section — and what doesn't. Use this w ### Overview - **Belongs**: Build on Base landing page and Vibenet testing guide. -- **Does not belong**: Chain-level concepts (fees, finality, throughput) — those go in Base Protocol → Core Primitives. +- **Does not belong**: Chain-level concepts (fees, finality, throughput) — those go in Specifications → Transactions. ### Integrate DeFi @@ -56,17 +56,17 @@ What belongs in each navigation tab and section — and what doesn't. Use this w ### Tokenize Assets - **Belongs**: Step-by-step guides for asset tokenization: create an asset token, issue units, restrict holders, cancel blocked units, announce distributions, apply multipliers, and pause transfers. -- **Does not belong**: B20 Asset variant specification details (those live in Base Protocol → Core Primitives → B20). +- **Does not belong**: B20 Asset variant specification details (those live in Specifications → B20). ### Issue Stablecoins - **Belongs**: End-to-end guides for stablecoin issuers: deploy, mint, burn, restrict holders, block accounts, recover funds, pause, reconcile with memos. Each page is a task the issuer completes. -- **Does not belong**: The B20 specification itself (that's Base Protocol → Core Primitives → B20). These guides *use* B20 but don't *define* it. +- **Does not belong**: The B20 specification itself (that's Specifications → B20). These guides *use* B20 but don't *define* it. ### Accept Payments - **Belongs**: Guides for requesting, authorizing, capturing, verifying, and reconciling payments, plus refunds, payouts, splits, scheduled charges, and agentic payments. -- **Does not belong**: B20 memo specification (Base Protocol → Core Primitives → B20). x402 protocol spec. +- **Does not belong**: B20 memo specification (Specifications → B20). x402 protocol spec. --- @@ -74,44 +74,72 @@ What belongs in each navigation tab and section — and what doesn't. Use this w **Audience**: Developers and technical users who need to understand how Base works at the chain level — primitives, protocol internals, network configuration, and node operations. -### Base Protocol (Landing) +Content is organized by topic, not by abstraction level. Each topic group flows from user-facing overview to deep protocol spec, so developers find everything about a subject in one place. -- **Belongs**: Chain overview, connecting to Base quickstart, faucets. Entry points into the protocol tab. -- **Does not belong**: Integration guides or solutions-first style writing. This section is meant for technical-first style writing. SDK setup (that's SDKs & APIs). +**Changelog pattern**: Each topic group should include a changelog summary page that lists what changed per hardfork and links out to the detail entries in the Upgrades tab. The summary page lives here; the detail pages live in Upgrades under the hardfork that introduced them. -### Core Primitives +**Content structure**: See the [Specification Pages](../content-guidelines.md#specification-pages) section of the content guidelines for page types, page structure, and writing rules. -- **Belongs**: Specifications and reference material for Base-native primitives that developers interact with directly: B20 token standard (full spec, interfaces, constants, errors, invariants), native account abstraction, bridging options, network fees, transaction ordering/finality, Flashblocks. -- **Does not belong**: How-to guides for using these primitives (those go in Build on Base). API endpoint reference (SDKs & APIs). Per-hardfork changelog detail pages (those go in Upgrades → the hardfork group). -- **Changelog pattern**: Each feature or subsystem in Core Primitives should include a changelog summary page that lists what changed per hardfork and links out to the detail entries in the Upgrades tab. The summary page lives here; the detail pages live in Upgrades under the hardfork that introduced them. -- **Content structure**: See the [Specification Pages](../content-guidelines.md#specification-pages) section of the content guidelines for page types, page structure, and writing rules. +### Specifications (Landing) -#### B20 (Nested Group) +- **Belongs**: Chain overview, connecting to Base quickstart, faucets. Entry points into the Specifications tab. +- **Does not belong**: Integration guides or solutions-first style writing. This tab is meant for technical-first style writing. SDK setup (that's SDKs & APIs). + +### B20 - **Belongs**: The normative B20 specification: index page, constants and addresses, errors and events, invariants and tests, interface reference pages (IActivationRegistry, IB20, IB20Asset, IB20Factory, IB20Stablecoin, IPolicyRegistry), and a changelog summary page that links to the per-hardfork detail entries in the Upgrades tab. - **Does not belong**: Tutorials on deploying B20 tokens (Build on Base → Issue Stablecoins). Per-hardfork changelog detail pages (Upgrades → Cobalt, Beryl, etc.). The "B20 token standard" overview for general audiences (that's a network-information page, not the spec). -#### Bridging (Nested Group) +### Account Abstraction + +- **Belongs**: Native account abstraction specification for Base. Listed as a top-level page, not a dropdown group (single-page groups should be promoted to top-level pages). +- **Does not belong**: SDK integration guides for smart wallets (SDKs & APIs → Base Account SDK). + +### Bridging + +- **Belongs**: Standard bridges contract spec, deposits spec, withdrawals spec, cross-domain messengers spec, Base-Solana bridge. Include a changelog summary page linking to hardfork entries that changed bridging. +- **Does not belong**: User-facing bridge route picker (that's Get Started → Quickstart). How-to guides for building bridge integrations (Build on Base). Per-hardfork changelog detail pages (Upgrades). +- **Ordering**: Standard bridges → deposits → withdrawals → cross-domain messengers → Base-Solana bridge. Protocol specs first (general to specific), then the first-party ecosystem bridge. + +### Transactions + +- **Belongs**: Transaction ordering, transaction finality, network fees, throughput and limits, troubleshooting transactions. Everything about how transactions work on Base, from user experience to network parameters. +- **Does not belong**: Derivation pipeline or consensus specs (Consensus). Per-hardfork changelog detail pages (Upgrades). + +### Flashblocks + +- **Belongs**: Flashblocks reference — key concepts, architecture, and FAQ about block building, WebSocket data, RPC usage, and node setup. +- **Does not belong**: Flashblocks API methods (SDKs & APIs → Base Chain API). Transaction ordering details (Transactions). + +### Protocol Overview -- **Belongs**: Ecosystem bridges overview, Base-Solana bridge, bridging and withdrawals user guide, and a changelog summary page linking to hardfork entries that changed bridging. -- **Does not belong**: Protocol-level bridging specs (those go in Network Systems → Bridging). +- **Belongs**: Design philosophy and lineage (specs/overview), and the detailed protocol architecture with component diagrams and user flow walkthroughs (specs/protocol/overview). +- **Does not belong**: Per-component specs (those go in their respective topic groups: Consensus, Execution, Proofs, etc.). -#### Transactions (Nested Group) +### Batcher -- **Belongs**: Transaction ordering, transaction finality — how users experience transactions. Include a changelog summary page linking to hardfork entries that changed transaction behavior. -- **Does not belong**: Derivation pipeline or consensus specs (Network Systems → Consensus). +- **Belongs**: Batcher specification — how transaction batches are compressed and posted to Ethereum for data availability. +- **Does not belong**: Derivation details (Consensus). Hardfork-specific batcher changes (Upgrades). -### Network Systems +### Consensus -- **Belongs**: Protocol-level specifications: batcher, bridging internals (deposits, withdrawals, messengers), consensus (derivation, P2P, RPC), execution (precompiles, predeploys, preinstalls), proofs (challenger, proposer, registrar, TEE prover, ZK prover, contracts), throughput and limits. -- **Does not belong**: User-facing network info (fees, faucets — those are Core Primitives or the landing group). Hardfork-specific changes (Upgrades). B20 spec (Core Primitives). -- **Changelog pattern**: Same as Core Primitives — each subsystem (batcher, consensus, execution, proofs, etc.) should include a changelog summary page that lists per-hardfork changes and links out to the detail entries in the Upgrades tab. -- **Content structure**: See the [Specification Pages](../content-guidelines.md#specification-pages) section of the content guidelines — same page types and writing rules as Core Primitives. +- **Belongs**: Consensus specifications: derivation pipeline, P2P networking, RPC methods for consensus. +- **Does not belong**: Batcher (separate group). Execution engine details (Execution). Hardfork-specific changes (Upgrades). + +### Execution + +- **Belongs**: Execution specifications: EVM precompiles, predeploys, preinstalls. +- **Does not belong**: Consensus or derivation details (Consensus). Hardfork-specific changes (Upgrades). + +### Proofs + +- **Belongs**: Proof system specifications: challenger, proposer, registrar, TEE prover, ZK prover, proof contracts. +- **Does not belong**: Consensus or derivation details (Consensus). Hardfork-specific changes (Upgrades). ### Reference -- **Belongs**: Node providers list, base contracts, glossary, configurability reference, troubleshooting transactions. Lookup-oriented content. -- **Does not belong**: The B20 spec (that moved to Core Primitives). API endpoints (SDKs & APIs). Step-by-step guides of any kind. +- **Belongs**: Builder codes, base contracts, smart contracts, configurability reference, glossary. Lookup-oriented content. +- **Does not belong**: The B20 spec (that's in B20). API endpoints (SDKs & APIs). Step-by-step guides of any kind. ### Node Operators @@ -137,7 +165,7 @@ What belongs in each navigation tab and section — and what doesn't. Use this w ### Base Chain API - **Belongs**: RPC overview, Ethereum JSON-RPC API methods, Flashblocks API methods, Debug API methods. Each page documents one RPC endpoint. -- **Does not belong**: SDK wrapper methods (Base Account SDK). Flashblocks conceptual explainer (Base Protocol → Core Primitives). Node setup (Base Protocol → Node Operators). +- **Does not belong**: SDK wrapper methods (Base Account SDK). Flashblocks conceptual explainer (Specifications → Flashblocks). Node setup (Base Protocol → Node Operators). ### Base Account SDK @@ -170,7 +198,7 @@ What belongs in each navigation tab and section — and what doesn't. Use this w ### Optimism (Hardfork Groups) - **Belongs**: Upstream OP Stack hardfork specs that Base inherits (Jovian, Isthmus, Holocene, Granite, Fjord, Ecotone, Delta, Canyon). Each gets an overview plus per-component pages (exec-engine, derivation, predeploys, etc.). -- **Does not belong**: Base-specific hardfork content (use the Base-named groups above). Current protocol specs (Base Protocol → Network Systems). +- **Does not belong**: Base-specific hardfork content (use the Base-named groups above). Current protocol specs (Specifications → topic groups). --- @@ -180,12 +208,13 @@ Key IA decisions from past reorganizations, for context: | Decision | Rationale | |----------|-----------| -| B20 spec moved from Reference to Core Primitives | B20 is a first-class primitive developers interact with, not a lookup reference | +| Topic-based groups replace Core Primitives / Network Systems | Developers navigate by topic (bridging, transactions), not by abstraction level (user-facing vs protocol internals). The old split created duplicate sidebar groups (two "Bridging" sections) and arbitrary placement decisions. Topic-based groups flow from overview → deep spec within each subject. | +| B20 spec moved from Reference to its own group | B20 is a first-class primitive developers interact with, not a lookup reference | | How-to guides separated from specs | Build on Base is task-oriented (issue, accept, tokenize); Specifications is concept/spec-oriented | | API reference lives in SDKs & APIs, not Specifications | Developers looking for RPC methods think "API docs", not "protocol" | -| Hardfork specs live in Upgrades, not Network Systems | Network Systems is the *current* canonical state; Upgrades tracks *deltas* | +| Hardfork specs live in Upgrades, not topic groups | Topic groups are the *current* canonical state; Upgrades tracks *deltas* | | No per-feature upgrade groups | Feature changes (e.g., B20) go under the hardfork that introduced them (Cobalt, Beryl), not a standalone section | -| Changelog summary pages in Specifications | Each Core Primitives and Network Systems feature gets a changelog summary page that links out to detail entries in the Upgrades tab — Specifications owns the spec and the summary, Upgrades owns the migration details | +| Changelog summary pages in Specifications | Each topic group gets a changelog summary page that links out to detail entries in the Upgrades tab — Specifications owns the spec and the summary, Upgrades owns the migration details | | Node operators stay in Specifications | Node ops are protocol-adjacent, not SDK/API work | | Get Started → Solutions are entry ramps only | They link to Build on Base guides, they don't duplicate them | | Mini Apps renamed to Apps | Broader scope, `/mini-apps/` paths redirect to `/apps/` | @@ -193,6 +222,12 @@ Key IA decisions from past reorganizations, for context: --- +## Navigation Structure + +- **No single-page dropdown groups**: If a group contains only one page, remove the group wrapper and list the page as a top-level nav item instead. A dropdown that expands to reveal a single link adds a click without adding value. + +--- + ## Naming Conventions - **Page titles**: Title case — capitalize all words except short conjunctions and articles (e.g., "Integrate an Earn Product") From f2d543b39c3e5fcea3266d10f03f48bb0f1ea25e Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Fri, 28 Aug 2026 16:52:35 -0400 Subject: [PATCH 2/3] fix: add redirects for orphan pages removed from nav Co-Authored-By: Claude Opus 4.6 --- docs/docs.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/docs.json b/docs/docs.json index 1380ae030..6e874df7d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -868,6 +868,14 @@ "source": "/base-chain/network-information/bridging-and-withdrawals", "destination": "/base-chain/specs/protocol/bridging/withdrawals" }, + { + "source": "/base-chain/network-information/network-faucets", + "destination": "/get-started/get-funds" + }, + { + "source": "/base-chain/quickstart/connecting-to-base", + "destination": "/get-started/connect-to-base" + }, { "source": "/base-account", "destination": "/sdks/base-account/overview" From a6eb38e7e8677b01d09d168dd58a3c49071edc97 Mon Sep 17 00:00:00 2001 From: mind-apivessa Date: Fri, 28 Aug 2026 16:58:24 -0400 Subject: [PATCH 3/3] fix: resolve orphan pages and redirect chains Add orphan pages to .mintignore and update old redirects to point directly to final destinations instead of through intermediate pages. Co-Authored-By: Claude Opus 4.6 --- docs/.mintignore | 5 +++++ docs/docs.json | 18 +++++++++--------- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/.mintignore b/docs/.mintignore index 46dd9a093..9844e52b4 100644 --- a/docs/.mintignore +++ b/docs/.mintignore @@ -3,3 +3,8 @@ writing.md API_MIGRATION_PLAN.md tone_of_voice.mdx + +# Pages removed from nav and redirected elsewhere +base-chain/network-information/bridging-and-withdrawals.mdx +base-chain/network-information/network-faucets.mdx +base-chain/quickstart/connecting-to-base.mdx diff --git a/docs/docs.json b/docs/docs.json index 6e874df7d..a56be27df 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1966,7 +1966,7 @@ }, { "source": "/base-chain/tools/network-faucets", - "destination": "/base-chain/network-information/network-faucets" + "destination": "/get-started/get-funds" }, { "source": "/base-chain/tools/node-providers", @@ -2326,7 +2326,7 @@ }, { "source": "/chain/connecting-to-base", - "destination": "/base-chain/quickstart/connecting-to-base" + "destination": "/get-started/connect-to-base" }, { "source": "/chain/cross-chain", @@ -2370,11 +2370,11 @@ }, { "source": "/chain/network-faucets", - "destination": "/base-chain/network-information/network-faucets" + "destination": "/get-started/get-funds" }, { "source": "/chain/network-information", - "destination": "/base-chain/quickstart/connecting-to-base" + "destination": "/get-started/connect-to-base" }, { "source": "/chain/node-performance", @@ -2434,7 +2434,7 @@ }, { "source": "/chain/using-base", - "destination": "/base-chain/quickstart/connecting-to-base" + "destination": "/get-started/connect-to-base" }, { "source": "/chain/wallet", @@ -2542,11 +2542,11 @@ }, { "source": "/docs/network-information", - "destination": "/base-chain/quickstart/connecting-to-base" + "destination": "/get-started/connect-to-base" }, { "source": "/docs/tools/network-faucets", - "destination": "/base-chain/network-information/network-faucets" + "destination": "/get-started/get-funds" }, { "source": "/feedback", @@ -2894,7 +2894,7 @@ }, { "source": "/network-information", - "destination": "/base-chain/quickstart/connecting-to-base" + "destination": "/get-started/connect-to-base" }, { "source": "/quickstart", @@ -2910,7 +2910,7 @@ }, { "source": "/tools/network-faucets", - "destination": "/base-chain/network-information/network-faucets" + "destination": "/get-started/get-funds" }, { "source": "/tutorials/deploy-with-foundry",