feat: Migrate to mdbook (#16)

* Initial move

* Updates

* lints

* just directive for `mdbook serve`

* Remove toc lint

* Workflow

* Add `mdbook-mermaid`

.circleci/config.yml

@@ -1,16 +1,13 @@
 version: 2.1
-
 orbs:
   slack: circleci/[email protected]
-
 parameters:
   ci_builder_image:
     type: string
     default: us-docker.pkg.dev/oplabs-tools-artifacts/images/ci-builder:v0.35.0
   base_image:
     type: string
     default: ubuntu-2204:2022.07.1
-
 commands:
   notify-failures-on-develop:
     description: "Notify Slack"
@@ -24,7 +21,6 @@ commands:
           event: fail
           template: basic_fail_1
           branch_pattern: develop
-
 jobs:
   lint-specs:
     docker:
@@ -37,10 +33,6 @@ jobs:
       - run:
           name: markdown lint
           command: just lint-specs-md-check
-      - run:
-          name: toc lint
-          command: just lint-specs-toc-check
-
   lint-links:
     machine:
       image: <<pipeline.parameters.base_image>>
@@ -51,18 +43,16 @@ jobs:
           command: just lint-links
       - notify-failures-on-develop:
           channel: C055R639XT9 #notify-link-check
-
 workflows:
   specs-check:
     when:
       not:
-        equal: [ scheduled_pipeline, << pipeline.trigger_source >> ]
+        equal: [scheduled_pipeline, << pipeline.trigger_source >>]
     jobs:
       - lint-specs
-
   scheduled-links-check:
     when:
-      equal: [ build_daily, <<pipeline.schedule.name>> ]
+      equal: [build_daily, <<pipeline.schedule.name>>]
     jobs:
       - lint-links:
           context: slack

.github/workflows/deploy.yaml

@@ -0,0 +1,35 @@
+name: Book Deployment
+on:
+  push:
+    branches:
+      - main
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      deployments: write
+    name: Publish to GitHub Pages
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+      - name: Install Rust stable toolchain
+        uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Setup mdbook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: "latest"
+      - name: Install mdbook plugins
+        run: |
+          cargo install mdbook-katex mdbook-toc mdbook-linkcheck mdbook-mermaid
+      - name: Build book
+        run: mdbook build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/html

.gitignore

@@ -1 +1,4 @@
-node_modules/**
+# Rendered book
+book/
+
+node_modules/**

.markdownlint.json

@@ -7,6 +7,7 @@
     "tables": false
   },
   "no-blanks-blockquote": false,
+  "no-empty-links": false,
   "single-title": false,
   "no-emphasis-as-heading": false
 }

Justfile

@@ -7,10 +7,10 @@ lint-specs-md-check:
 lint-specs-md-fix:
     npx markdownlint-cli2-fix "./specs/**/*.md"
 
-lint-specs-toc-check:
-    npx doctoc '--title=**Table of Contents**' ./specs
-
 lint-links:
     docker run --init -it -v `pwd`:/input lycheeverse/lychee --verbose --no-progress --exclude-loopback \
     		--exclude twitter.com --exclude explorer.optimism.io --exclude linux-mips.org --exclude vitalik.ca \
-    		--exclude-mail /input/README.md "/input/specs/**/*.md"
+    		--exclude-mail /input/README.md "/input/specs/**/*.md"
+
+serve:
+    mdbook serve

README.md

@@ -1,63 +1,34 @@
-<!-- DOCTOC SKIP -->
-# Optimism Bedrock specs
-
-This directory contains the plain english specs for Optimism, a minimal optimistic rollup protocol
-that maintains 1:1 compatibility with Ethereum.
-
-## Specification Contents
-
-- [Introduction](specs/introduction.md)
-- [Overview](specs/overview.md)
-- [Deposits](specs/deposits.md)
-- [Withdrawals](specs/withdrawals.md)
-- [Execution Engine](specs/exec-engine.md)
-- [L2 Output Root Proposals](specs/proposals.md)
-- [Rollup Node](specs/rollup-node.md)
-- [Rollup Node P2p](specs/rollup-node-p2p.md)
-- [L2 Chain Derivation](specs/derivation.md)
-- [Superchain Upgrades](specs/superchain-upgrades.md)
-- [System Config](specs/system_config.md)
-- [Batch Submitter](specs/batcher.md)
-- [Guaranteed Gas Market](specs/guaranteed-gas-market.md)
-- [Messengers](specs/messengers.md)
-- [Bridges](specs/bridges.md)
-- [Predeploys](specs/predeploys.md)
-- [Glossary](specs/glossary.md)
-
-### Experimental
-
-Specifications of new features in active development.
-
-- [Fault Proof](specs/fault-proof.md)
-- [Dispute Game Interface](specs/dispute-game-interface.md)
-- [Fault Dispute Game](specs/fault-dispute-game.md)
-- [Cannon VM](specs/cannon-fault-proof-vm.md)
-
-## Design Goals
-
-Our aim is to design a protocol specification that is:
-
-- **Fast:** When users send transactions, they get reliable confirmations with low-latency.
-  For example when swapping on Uniswap you should see that your transaction succeed in less than 2
-  seconds.
-- **Scalable:** It should be possible to handle an enormous number of transactions
-  per second which will enable the system to charge low fees.
-  V1.0 will enable Optimism to scale up to and even past the gas limit on L1.
-  Later iterations should scale much further.
-- **Modular:** Our designs will use modularity to reduce complexity and enable parallel
-  contributions. Coming up with good conceptual frameworks & composable atoms of software enables us
-  to build extremely complex software even when any one person cannot hold that much in their brain.
-- **Minimal:** Rollups should be minimal to best take advantage of the battle-tested infrastructure
-  (like Geth) that already runs Ethereum. An ideal optimistic rollup design should be representable
-  as a *diff* against Ethereum client software.
-- **Developer Driven:** Our designs will be developer driven to ensure we are actually building
-  something that people want to use. We must constantly engage with the developers who will be using
-  our software to avoid creating a system no one wants to use.
-- **Clear and Readable:** The specs we write are written to be read. So tight feedback loop with the
-  systems team consuming the spec is also key!
-- **Secure:** This is self-evident.
-  User’s assets are at stake. Every component of the system must be incredibly secure.
-- **Decentralizable:** Optimism must be designed to avail itself of the security and
-  censorship-resistant guarantees achieved by a decentralized system.
-  Currently centralized components of the system should have a clear path towards decentralization.
-  Already decentralized components of the system should be protected and preserved.
+<div align="center">
+  <br />
+  <br />
+  <a href="https://optimism.io"><img alt="Optimism" src="https://raw.githubusercontent.com/ethereum-optimism/brand-kit/main/assets/svg/OPTIMISM-R.svg" width=600></a>
+  <br />
+  <h3><a href="https://optimism.io">Optimism</a> is Ethereum, scaled.</h3>
+  <br />
+</div>
+
+## OP Stack Specification
+
+This repository contains the [Specs Book](https://static.optimism.io/specs).
+
+## Contributing
+
+### Dependencies
+
+**Rust Toolchain**
+
+```sh
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+**`mdbook` + plugins**
+
+```sh
+cargo install mdbook mdbook-katex mdbook-toc mdbook-linkcheck mdbook-mermaid
+```
+
+### Serving the book locally
+
+```sh
+mdbook serve
+```

book.toml

@@ -0,0 +1,22 @@
+[book]
+authors = ["optimism-collective"]
+language = "en"
+multilingual = false
+src = "specs"
+title = "OP Stack Specification"
+
+[preprocessor.katex]
+after = ["links"]
+
+[preprocessor.toc]
+command = "mdbook-toc"
+renderer = ["html"]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html]
+default-theme = "ayu"
+additional-js = ["specs/static/solidity.min.js", "specs/static/mermaid.min.js", "specs/static/mermaid-init.js"]
+
+[output.linkcheck]

package.json

@@ -7,7 +7,6 @@
     "pnpm": ">=8"
   },
   "dependencies": {
-    "doctoc": "^2.2.0",
     "markdownlint-cli2": "0.4.0"
   }
-}
+}