feat: doctoc (#22)

* doctoc: reintroduce

* lint

* doctoc: cleanup

* fixup

* ci: fix

.circleci/config.yml

@@ -33,6 +33,9 @@ jobs:
       - run:
           name: markdown lint
           command: just lint-specs-md-check
+      - run:
+          name: markdown toc
+          command: just lint-specs-toc-check
   lint-links:
     machine:
       image: <<pipeline.parameters.base_image>>

.github/workflows/deploy.yaml

@@ -24,7 +24,7 @@ jobs:
           mdbook-version: "latest"
       - name: Install mdbook plugins
         run: |
-          cargo install mdbook-katex mdbook-toc mdbook-linkcheck mdbook-mermaid
+          cargo install mdbook-katex mdbook-linkcheck mdbook-mermaid
       - name: Build book
         run: mdbook build
       - name: Deploy

Justfile

@@ -7,6 +7,9 @@ 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 \

README.md

@@ -24,11 +24,44 @@ 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
+cargo install mdbook mdbook-katex mdbook-linkcheck mdbook-mermaid
 ```
 
 ### Serving the book locally
 
 ```sh
-mdbook serve
+just serve
 ```
+
+### Linting
+
+`doctoc` is used to automatically add a table of contents.
+
+```sh
+just lint-specs-toc-check
+```
+
+To fix markdown linting errors:
+
+```sh
+just lint-specs-md-fix
+```
+
+See the [markdownlint rule reference](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
+and an example [config file](https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.jsonc).
+
+Justification for linting rules in
+[.markdownlint.json](https://github.com/ethereum-optimism/specs/blob/main/.markdownlint.json):
+
+- _line_length_ (`!strict && stern`): don't trip up on url lines
+- _no-blanks-blockquote_: enable multiple consecutive blockquotes separated by white lines
+- _single-title_: enable reusing `<h1>` for content
+- _no-emphasis-as-heading_: enable emphasized paragraphs
+
+To lint links:
+
+```sh
+just lint-links
+```
+
+[lychee][lychee] is used for linting links.

book.toml

@@ -8,10 +8,6 @@ title = "OP Stack Specification"
 [preprocessor.katex]
 after = ["links"]
 
-[preprocessor.toc]
-command = "mdbook-toc"
-renderer = ["html"]
-
 [preprocessor.mermaid]
 command = "mdbook-mermaid"
 

package.json

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