docs: fix broken links, stale flag prefixes, and formatting issues (#3112)

alpe · web-flow · commit 1c49f44b540e · 2026-02-27T14:16:20.000+01:00
* docs: fix broken links, stale --rollkit.* flag prefixes, and escaped backticks

- Fix forced-inclusion.md: based.md → based-sequencing.md (2 links)
- Fix block-lifecycle.md: da.md → data-availability.md (2 links)
- Fix reference/specs/overview.md: p2p.md → learn/specs/p2p.md
- Fix running-nodes/full-node.md: relative paths to guides/
- Fix what-is-evolve.md: remove escaped backticks around ev-node
- Replace all --rollkit.* flags with --evnode.* in ev-node-config.md
- Fix visualizer.md: --rollkit.rpc → --evnode.rpc

* docs: fix markdownlint errors (MD040 missing code block languages, MD012 extra blank lines)

- Add 'text' language specifier to 25 fenced code blocks containing ASCII
  diagrams, log output, and formulas
- Remove extra blank line in migration-from-cometbft.md
- Fix non-descriptive link text in deployment.md
diff --git a/docs/concepts/block-lifecycle.md b/docs/concepts/block-lifecycle.md
@@ -428,7 +428,7 @@ The retrieval system uses persistent caches for both headers and data:
 - Enables efficient sync from P2P and DA sources
 - Maintains namespace migration state for optimized retrieval
 
-For more details on DA integration, see the [Data Availability specification](./da.md).
+For more details on DA integration, see the [Data Availability specification](./data-availability.md).
 
 #### Out-of-Order Chain Blocks on DA
 
@@ -725,7 +725,7 @@ See [tutorial] for running a multi-node network with both aggregator and non-agg
 
 [7] [Evolve Minimal Header](../../adr/adr-015-rollkit-minimal-header.md)
 
-[8] [Data Availability](./da.md)
+[8] [Data Availability](./data-availability.md)
 
 [9] [Lazy Aggregation with DA Layer Consistency ADR](../../adr/adr-021-lazy-aggregation.md)
 
diff --git a/docs/concepts/data-availability.md b/docs/concepts/data-availability.md
@@ -30,7 +30,7 @@ Evolve currently supports two DA modes:
 
 ## DA Flow
 
-```
+```text
 Block Produced
       │
       ▼
diff --git a/docs/concepts/fee-systems.md b/docs/concepts/fee-systems.md
@@ -8,7 +8,7 @@ Evolve chains have two layers of fees: execution fees (paid to process transacti
 
 Uses EIP-1559 fee model:
 
-```
+```text
 Transaction Fee = (Base Fee + Priority Fee) × Gas Used
 ```
 
@@ -38,7 +38,7 @@ See [Base Fee Redirect](/ev-reth/features/base-fee-redirect) for details.
 
 Uses standard Cosmos SDK fee model:
 
-```
+```text
 Transaction Fee = Gas Price × Gas Used
 ```
 
@@ -107,7 +107,7 @@ da:
 
 ## Fee Flow Diagram
 
-```
+```text
 User Transaction
       │
       │ Pays: Gas Price × Gas
diff --git a/docs/concepts/finality.md b/docs/concepts/finality.md
@@ -4,7 +4,7 @@ Finality determines when a transaction is irreversible. Evolve has a multi-stage
 
 ## Finality Stages
 
-```
+```text
 Transaction Submitted
         │
         ▼
diff --git a/docs/concepts/sequencing.md b/docs/concepts/sequencing.md
@@ -18,7 +18,7 @@ In traditional L1 blockchains, these functions are distributed across validators
 
 The simplest approach is a single sequencer: one designated node that orders all transactions.
 
-```
+```text
 User → Sequencer → Block → DA Layer
 ```
 
@@ -41,7 +41,7 @@ Most production rollups today use single sequencers because the performance bene
 
 Based sequencing (also called "based rollups") delegates transaction ordering to the underlying DA layer. Instead of a dedicated sequencer, users submit transactions directly to the DA layer, and all rollup nodes independently derive the same ordering from DA blocks.
 
-```
+```text
 User → DA Layer → All Nodes Derive Same Order
 ```
 
diff --git a/docs/ev-abci/integration-guide.md b/docs/ev-abci/integration-guide.md
@@ -71,7 +71,7 @@ Check for ev-abci flags:
 
 Expected flags:
 
-```
+```text
 --evnode.node.aggregator     Run as block producer
 --evnode.da.address          DA layer address
 --evnode.signer.passphrase   Signer passphrase
diff --git a/docs/ev-abci/migration-from-cometbft.md b/docs/ev-abci/migration-from-cometbft.md
@@ -269,4 +269,3 @@ Verify that the node starts successfully:
 ```
 
 Your node is now running with `ev-abci` instead of CometBFT. The chain continues from the same state but with the new consensus engine.
-
diff --git a/docs/ev-abci/overview.md b/docs/ev-abci/overview.md
@@ -13,7 +13,7 @@ ev-abci provides:
 
 ## Architecture
 
-```
+```text
 ┌─────────────────────────────────────────┐
 │            Your Cosmos App              │
 │  ┌─────────────────────────────────┐    │
diff --git a/docs/ev-reth/engine-api.md b/docs/ev-reth/engine-api.md
@@ -22,7 +22,7 @@ Configure both sides:
 
 ## Block Production Flow
 
-```
+```text
 ev-node                                    ev-reth
    │                                          │
    │  1. engine_forkchoiceUpdatedV3           │
diff --git a/docs/ev-reth/features/base-fee-redirect.md b/docs/ev-reth/features/base-fee-redirect.md
@@ -32,7 +32,7 @@ In your chainspec (`genesis.json`):
 
 ## How It Works
 
-```
+```text
 Transaction Fee = Base Fee + Priority Fee
 
 Standard Ethereum:
diff --git a/docs/ev-reth/overview.md b/docs/ev-reth/overview.md
@@ -12,7 +12,7 @@ ev-reth extends reth with:
 
 ## Architecture
 
-```
+```text
 ┌─────────────────────────────────────────┐
 │               ev-node                    │
 │         (consensus + DA + P2P)          │
diff --git a/docs/getting-started/choose-your-path.md b/docs/getting-started/choose-your-path.md
@@ -93,7 +93,7 @@ Use a custom executor if you need something neither EVM nor Cosmos SDK provides.
 
 ## Decision Tree
 
-```
+```text
 Do you have an existing Cosmos SDK chain?
 ├── Yes → Cosmos SDK (ev-abci)
 └── No
diff --git a/docs/getting-started/cosmos/quickstart.md b/docs/getting-started/cosmos/quickstart.md
@@ -62,7 +62,7 @@ mychaind start \
 
 You should see blocks being produced:
 
-```
+```text
 INF block marked as DA included blockHeight=1
 INF block marked as DA included blockHeight=2
 ```
diff --git a/docs/getting-started/evm/quickstart.md b/docs/getting-started/evm/quickstart.md
@@ -17,7 +17,7 @@ local-da
 
 You should see:
 
-```
+```text
 INF Listening on host=localhost port=7980
 ```
 
@@ -59,7 +59,7 @@ Initialize and start:
 
 You should see blocks being produced:
 
-```
+```text
 INF block marked as DA included blockHeight=1
 INF block marked as DA included blockHeight=2
 ```
diff --git a/docs/guides/advanced/forced-inclusion.md b/docs/guides/advanced/forced-inclusion.md
@@ -72,7 +72,7 @@ Epoch [100, 109] (epoch size = 10):
   - Sequencer includes forced tx in blocks before height 110
 ```
 
-See [Based Sequencing](./based.md) for a fully decentralized alternative that relies entirely on forced inclusion.
+See [Based Sequencing](./based-sequencing.md) for a fully decentralized alternative that relies entirely on forced inclusion.
 
 ## Detecting Malicious Sequencer Behavior
 
@@ -113,7 +113,7 @@ Nodes may require a coordinated restart into based sequencing mode, depending on
 - Users submit transactions directly to the DA layer going forward
 - Returning to single sequencer mode requires explicit governance and operational coordination
 
-See [Based Sequencing documentation](./based.md) for details on operating in this mode.
+See [Based Sequencing documentation](./based-sequencing.md) for details on operating in this mode.
 
 ## Advantages
 
diff --git a/docs/guides/da-layers/local-da.md b/docs/guides/da-layers/local-da.md
@@ -38,7 +38,7 @@ local-da
 
 Default output:
 
-```
+```text
 INF NewLocalDA: initialized LocalDA module=local-da
 INF Listening on host=localhost maxBlobSize=1974272 module=da port=7980
 INF server started listening on=localhost:7980 module=da
diff --git a/docs/guides/operations/deployment.md b/docs/guides/operations/deployment.md
@@ -8,7 +8,7 @@ This page is a deployment index. Use it to choose the right deployment guide for
 
 One of the benefits of building chains with Evolve is the flexibility you have as a developer to choose things like the DA layer, the settlement scheme, and the execution environment.
 
-You can learn more about Evolve architecture [here](../../learn/specs/overview.md).
+You can learn more about [Evolve architecture](../../learn/specs/overview.md).
 
 The challenge that comes with this flexibility is that there are more services that now need to be deployed and managed while running your chain.
 
diff --git a/docs/guides/operations/troubleshooting.md b/docs/guides/operations/troubleshooting.md
@@ -63,7 +63,7 @@ ls -la ~/.evnode/data
 
 **Error example:**
 
-```
+```text
 ERR DA layer submission failed error="connection refused"
 ```
 
@@ -93,7 +93,7 @@ celestia header sync-state
 
 **Error example:**
 
-```
+```text
 ERR DA layer submission failed error="Codespace: 'sdk', Code: 19, Message: "
 ```
 
diff --git a/docs/guides/running-nodes/full-node.md b/docs/guides/running-nodes/full-node.md
@@ -4,11 +4,11 @@
 
 This guide covers how to set up a full node to run alongside a sequencer node in a Evolve-based blockchain network. A full node maintains a complete copy of the blockchain and helps validate transactions, improving the network's decentralization and security.
 
-> **Note: The guide on how to run an Evolve EVM full node can be found [in the evm section](./evm/single.md#setting-up-a-full-node).**
+> **Note: The guide on how to run an Evolve EVM full node can be found [in the evm section](../../guides/evm/single.md#setting-up-a-full-node).**
 
 ## Prerequisites
 
-Before proceeding, ensure that you have completed the [build a chain](./gm-world.md) tutorial, which covers setting-up, building and running your chain.
+Before proceeding, ensure that you have completed the [build a chain](../../guides/gm-world.md) tutorial, which covers setting-up, building and running your chain.
 
 Ensure that you have:
 
diff --git a/docs/guides/tools/visualizer.md b/docs/guides/tools/visualizer.md
@@ -22,7 +22,7 @@ The DA Visualizer is disabled by default. To enable it, use the following config
 ### Via Command-line Flag
 
 ```bash
-testapp start --rollkit.rpc.enable_da_visualization
+testapp start --evnode.rpc.enable_da_visualization
 ```
 
 ### Via Configuration File
@@ -38,7 +38,7 @@ rpc:
 
 Once enabled, the DA Visualizer is accessible through your node's RPC server. By default, this is:
 
-```
+```text
 http://localhost:7331/da
 ```
 
diff --git a/docs/overview/architecture.md b/docs/overview/architecture.md
@@ -4,7 +4,7 @@ Evolve uses a modular architecture where each component has a well-defined inter
 
 ## System Overview
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────┐
 │                          Client Apps                            │
 │                    (wallets, dapps, indexers)                   │
@@ -51,7 +51,7 @@ The block package is the heart of ev-node. It's organized into specialized compo
 
 ### Component Interaction
 
-```
+```text
                     ┌─────────────┐
                     │   Reaper    │
                     │  (tx scrape)│
@@ -113,7 +113,7 @@ Full nodes sync and validate without producing blocks:
 
 ### Block Production (Aggregator)
 
-```
+```text
 User Tx → Execution Layer Mempool
                  │
                  ▼
@@ -137,7 +137,7 @@ User Tx → Execution Layer Mempool
 
 ### Block Sync (Non-Aggregator)
 
-```
+```text
 ┌────────────────────────────────────────┐
 │              Syncer                    │
 ├────────────┬────────────┬──────────────┤
diff --git a/docs/overview/what-is-evolve.md b/docs/overview/what-is-evolve.md
@@ -14,7 +14,7 @@ Evolve is a launch stack for L1s. It gives you full control over execution — w
 
 Evolve is [open-source](https://github.com/evstack/ev-node), production-ready, and fully composable.
 
-At its core is \`ev-node\`, a modular node that exposes an [Execution interface](https://github.com/evstack/ev-node/blob/main/core/execution/execution.go), — letting you bring any VM or execution logic, including Cosmos SDK or custom-built runtimes.
+At its core is `ev-node`, a modular node that exposes an [Execution interface](https://github.com/evstack/ev-node/blob/main/core/execution/execution.go) — letting you bring any VM or execution logic, including Cosmos SDK or custom-built runtimes.
 
 Evolving from Cosmos SDK?
 
diff --git a/docs/reference/api/engine-api.md b/docs/reference/api/engine-api.md
@@ -6,7 +6,7 @@ Engine API methods used by ev-node to communicate with ev-reth.
 
 All requests require JWT authentication via the `Authorization` header:
 
-```
+```text
 Authorization: Bearer <jwt_token>
 ```
 
diff --git a/docs/reference/configuration/ev-node-config.md b/docs/reference/configuration/ev-node-config.md
diff --git a/docs/reference/specs/overview.md b/docs/reference/specs/overview.md

Original file line number	Diff line number	Diff line change
`@@ -269,4 +269,3 @@ Verify that the node starts successfully:`
`269`	`269`	```
`270`	`270`
`271`	`271`	Your node is now running with `ev-abci` instead of CometBFT. The chain continues from the same state but with the new consensus engine.
`272`		`-`