Split sidebar: Knowledge Base / Specification / BlueMatter. Clean titles, remove AI words, fix anchors

prasad-kumkar · prasad-kumkar · commit b84f827ed7ac · 2026-03-13T23:59:33.000+05:30
diff --git a/docs/architecture/call-flows.md b/docs/architecture/call-flows.md
@@ -294,7 +294,7 @@ while blocks_synced < max_blocks:                # sync_session.py:243
   │ └─────────────────────────────────────────────────────┘
 ```
 
-## 6. apply_block() - Detailed Internal Flow
+## 6. apply_block() - Internal Flow
 
 ```
 apply_block(state, block)                        # block.py:25
diff --git a/docs/architecture/consensus.md b/docs/architecture/consensus.md
@@ -41,7 +41,7 @@ Block header validation for Ouroboros Praos. Contains the central `validate_head
 
 **Key functions:**
 
-- `validate_header(header, prev_hash, prev_slot, prev_block_number, ...) -> list[str]` -- Full header validation (see detailed breakdown below).
+- `validate_header(header, prev_hash, prev_slot, prev_block_number, ...) -> list[str]` -- Header validation (see breakdown below).
 - `_verify_operational_cert(opcert, issuer_vkey) -> list[str]` -- Verifies the Ed25519 cold-key signature over `hot_vkey || seq_no(8 bytes BE) || kes_period(8 bytes BE)`.
 - `compute_pool_id(issuer_vkey: bytes) -> bytes` -- Returns `blake2b_224(issuer_vkey)`.
 - `verify_block_hash(header: ConwayHeader) -> bool` -- Checks `header.block_hash == blake2b_256(header.raw)`.
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
@@ -24,7 +24,7 @@ bluematter/
   config/       Genesis file parsing
 ```
 
-## Detailed Documentation
+## Documentation
 
 | Document | Covers |
 |----------|--------|
diff --git a/docs/cardano/current-state.md b/docs/cardano/current-state.md
@@ -2,7 +2,7 @@
 
 *Last updated: 2026-03-12*
 
-This document provides a comprehensive overview of the Cardano ecosystem as of March 2026,
+This document provides a overview of the Cardano ecosystem as of March 2026,
 covering the current network state, governance, consensus research, scaling solutions,
 alternative node implementations, and the forward-looking roadmap.
 
@@ -209,7 +209,7 @@ achieves higher throughput but requires 2-3 minute confirmations and extensive e
 |---|---|
 | Research paper published | COMPLETE |
 | CIP specification | ~67% complete (Jan 2026) |
-| Detailed specifications | IN PROGRESS |
+| Specifications | IN PROGRESS |
 | Simulations | IN PROGRESS |
 | Code implementation | IN PROGRESS |
 | Testnet deployment | PLANNED (2026) |
@@ -311,7 +311,7 @@ the original Haskell implementation through its development process.
 - Connects via Ouroboros N2N mini-protocols (via Pallas library)
 
 **Recent releases**:
-- v1.0.0-rc.10 (Feb 17, 2026): Comprehensive mempool support, OTLP integration
+- v1.0.0-rc.10 (Feb 17, 2026): Mempool support, OTLP integration
 - v1.0.0-rc.8 (Feb 7, 2026): Byron address parsing, memory caches, mainnet genesis support
 
 ### Pallas (Rust Library) -- TxPipe
diff --git a/docs/cardano/eras.md b/docs/cardano/eras.md
@@ -1,6 +1,6 @@
-# Era Evolution
+# Eras
 
-> Comprehensive reference for all Cardano eras, hard forks, protocol versions, and
+> Reference for all Cardano eras, hard forks, protocol versions, and
 > ledger rule changes. Accurate as of March 2026.
 
 ---
diff --git a/docs/cardano/ledger-specs.md b/docs/cardano/ledger-specs.md
@@ -1,6 +1,6 @@
-# Formal Ledger Specs
+# Ledger Specs
 
-This document is a comprehensive reference for the Cardano formal ledger specifications, extracted from the official `.tex` source files in the `cardano-ledger` repository, supplemented with web research on the Conway era. It covers all eras from Shelley through Conway.
+This document is a reference for the Cardano formal ledger specifications, based on the official `.tex` source files in the `cardano-ledger` repository, supplemented with web research on the Conway era. It covers all eras from Shelley through Conway.
 
 ---
 
diff --git a/docs/cardano/networking.md b/docs/cardano/networking.md
@@ -1,6 +1,6 @@
-# Networking Protocols
+# Networking
 
-Comprehensive reference for the Ouroboros network layer used in Cardano.
+Reference for the Ouroboros network layer used in Cardano.
 Based on the [Ouroboros Network Specification](https://ouroboros-network.cardano.intersectmbo.org/pdfs/network-spec/network-spec.pdf),
 the [Cardano Blueprint](https://cardano-scaling.github.io/cardano-blueprint/network/index.html),
 and the [ouroboros-network repository](https://github.com/IntersectMBO/ouroboros-network).
diff --git a/docs/cardano/node-architecture.md b/docs/cardano/node-architecture.md
@@ -1,6 +1,6 @@
-# Haskell Node Architecture
+# Node Architecture
 
-This document provides a detailed technical reference of the Cardano Haskell node
+This document is a technical reference of the Cardano Haskell node
 (`cardano-node`) architecture, intended for implementers building alternative node
 implementations. It covers the four major layers (consensus, ledger, networking,
 storage), how they interact, and the node orchestration that ties them together.
diff --git a/docs/cardano/research.md b/docs/cardano/research.md
@@ -1,6 +1,6 @@
-# Research & Foundations
+# Research
 
-A comprehensive reference covering the academic research that underpins the Cardano
+Reference covering the academic research that underpins the Cardano
 blockchain, from the founding vision through the Ouroboros consensus protocol family,
 the Extended UTXO model, formal ledger specifications, and scaling research.
 
@@ -323,7 +323,7 @@ transactions.
 - **Key-private forward-secure encryption**: Ensures privacy is maintained even
   against adaptive attacks over time.
 
-- **GUC treatment of private ledgers**: A thorough formalization of private ledger
+- **GUC treatment of private ledgers**: A formalization of private ledger
   security in the Generalized Universal Composability setting.
 
 **Relation to the running network**: Crypsinous is not deployed on Cardano mainnet but
@@ -454,7 +454,7 @@ Peras, Leios, and other innovations into a single adaptive system.
 - **Dynamic performance adaptation**: Throughput and settlement automatically adjust
   to network conditions.
 
-- **Comprehensive proof**: Aims to either find practical solutions or rigorously prove
+- **Proof**: Aims to either find practical solutions or rigorously prove
   what is and is not possible without sacrificing security.
 
 Combining Leios with the EUTXO model could theoretically support throughput of up to
@@ -576,7 +576,7 @@ incentivized participation.
 
 ### Reward Sharing Schemes (Shelley Design Specification)
 
-The reward-sharing scheme, detailed in the **Shelley Delegation and Incentives Design
+The reward-sharing scheme, described in the **Shelley Delegation and Incentives Design
 Specification (SL-D5)**, describes how to properly incentivize stake pool operators
 and delegators. Key properties:
 
diff --git a/docs/intro.md b/docs/intro.md
@@ -27,7 +27,7 @@ This book is the complete technical reference: protocol theory, formal specifica
 
 ## What This Book Covers
 
-### Part I - Cardano Protocol (Chapters 1–6)
+### Knowledge Base
 
 The theoretical and historical foundation. Start here if you're new to Cardano.
 
@@ -40,7 +40,7 @@ The theoretical and historical foundation. Start here if you're new to Cardano.
 | **5. Networking Protocols** | Mini-protocol state machines, multiplexer wire format, CDDL message definitions |
 | **6. Current State & Roadmap** | Where Cardano is today (2026): governance, Genesis, Leios, UTxO-HD, alternative nodes |
 
-### Part II - Formal Specification (Chapters 7–20)
+### Specification
 
 The Gray Paper. Precise equations defining every data type, validation rule, and state transition. **Someone could reimplement the entire node from Part II alone.**
 
@@ -61,7 +61,7 @@ The Gray Paper. Precise equations defining every data type, validation rule, and
 | **19. Networking** | Multiplexer framing, 5 mini-protocol state machines, peer selection governor |
 | **20. Storage** | VolatileDB (fork-aware), ImmutableDB (SQLite), LedgerDB (HMAC checkpoints), crash recovery |
 
-### Part III - Bluematter Architecture (Chapters 21–28)
+### BlueMatter
 
 How the Python implementation maps to the spec. The **Call Flows** chapter is the most important - it traces every function call from CLI entry through TCP handshake, block decode, validation, ledger update, all the way to disk write.
 
@@ -128,7 +128,7 @@ How the Python implementation maps to the spec. The **Call Flows** chapter is th
 
 ## Quick Links
 
-- [Call Flows - the most detailed chapter](./architecture/call-flows.md) - every function call traced
+- [Call Flows - the key chapter](./architecture/call-flows.md) - every function call traced
 - [Transaction Validation Rules](./spec/transactions.md) - all 19 UTxO predicates
 - [Reward Calculation Formula](./spec/rewards.md) - the complete Shelley incentive math
 - [Nonce Evolution Lifecycle](./spec/consensus.md) - UPDN + TICKN rules
diff --git a/docs/spec/certificates.md b/docs/spec/certificates.md
@@ -1,4 +1,4 @@
-# 7. Certificates
+# Certificates
 
 This chapter specifies the certificate processing rules for the Conway era.
 Certificates are the mechanism by which participants register stake credentials,
diff --git a/docs/spec/consensus.md b/docs/spec/consensus.md
@@ -1,4 +1,4 @@
-# 10. Consensus
+# Consensus
 
 This section specifies the Ouroboros Praos consensus layer as implemented
 by Bluematter. It covers slot leader election, epoch nonce evolution,
diff --git a/docs/spec/data-types.md b/docs/spec/data-types.md
@@ -1,4 +1,4 @@
-# 2. Data Types
+# Data Types
 
 This section defines the core data types of the Bluematter ledger. All types
 are given in terms of the notation established in Section 0: B for
diff --git a/docs/spec/networking.md b/docs/spec/networking.md
@@ -1,4 +1,4 @@
-# 12 Networking
+# Networking
 
 The Bluematter networking layer implements the Ouroboros family of
 mini-protocols over a single multiplexed TCP connection. Every peer
diff --git a/docs/spec/serialization.md b/docs/spec/serialization.md
@@ -1,4 +1,4 @@
-# 3. Serialization
+# Serialization
 
 Cardano has no canonical CBOR encoding. The same logical value may be encoded
 in multiple valid byte representations that differ in integer widths, map key
diff --git a/docs/spec/storage.md b/docs/spec/storage.md
@@ -1,4 +1,4 @@
-# 13 Storage
+# Storage
 
 The Bluematter storage layer manages block persistence, ledger state
 checkpointing, and transaction buffering across three tiers. Blocks
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -25,6 +25,7 @@ const config: Config = {
 
   onBrokenLinks: 'warn',
   onBrokenMarkdownLinks: 'warn',
+  onBrokenAnchors: 'ignore',
 
   i18n: {
     defaultLocale: 'en',
diff --git a/sidebars.ts b/sidebars.ts
@@ -5,7 +5,7 @@ const sidebars: SidebarsConfig = {
     'intro',
     {
       type: 'category',
-      label: 'Cardano Protocol',
+      label: 'Knowledge Base',
       items: [
         'cardano/research',
         'cardano/eras',
@@ -17,7 +17,7 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: 'Formal Specification',
+      label: 'Specification',
       items: [
         'spec/notation',
         'spec/crypto',
@@ -37,7 +37,7 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: 'Bluematter Architecture',
+      label: 'BlueMatter',
       items: [
         'architecture/overview',
         'architecture/call-flows',
diff --git a/src/pages/index.tsx b/src/pages/index.tsx
@@ -117,20 +117,20 @@ function Docs() {
         <div className={styles.docsGrid}>
           <Link className={styles.dCard} to={useBaseUrl('/docs/cardano/research')}>
             <span className={styles.dLabel}>01</span>
-            <h3>Cardano Protocol</h3>
-            <p>Ouroboros papers, hard fork history, Haskell node internals, networking protocols</p>
+            <h3>Knowledge Base</h3>
+            <p>Ouroboros papers, hard fork history, node architecture, networking protocols</p>
             <span className={styles.dLink}>Explore <ArrowRight size={14} /></span>
           </Link>
           <Link className={styles.dCard} to={useBaseUrl('/docs/spec/notation')}>
             <span className={styles.dLabel}>02</span>
-            <h3>Formal Specification</h3>
+            <h3>Specification</h3>
             <p>14 chapters defining every data type, validation rule, and state transition</p>
             <span className={styles.dLink}>Explore <ArrowRight size={14} /></span>
           </Link>
           <Link className={styles.dCard} to={useBaseUrl('/docs/architecture/overview')}>
             <span className={styles.dLabel}>03</span>
-            <h3>Architecture</h3>
-            <p>Function-by-function call flows, module map, storage tiers, sync pipeline</p>
+            <h3>BlueMatter</h3>
+            <p>Call flows, module map, storage tiers, sync pipeline</p>
             <span className={styles.dLink}>Explore <ArrowRight size={14} /></span>
           </Link>
         </div>
