feat: Book (#206)

### Description

Introduces an mdbook hosted at https://alloy-rs.github.io/op-alloy.

Also adds a github action workflow to publish the book.

.github/workflows/book.yml

@@ -0,0 +1,32 @@
+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
+        run: |
+          cargo install mdbook mdbook-mermaid mdbook-template
+      - name: Build book
+        working-directory: ./book
+        run: mdbook build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/book

book/.gitignore

@@ -0,0 +1 @@
+book

book/README.md

@@ -0,0 +1,15 @@
+# `op-alloy-book`
+
+This repository contains the source code for the op-alloy book, which is available at [alloy-rs.github.io/op-alloy](https://alloy-rs.github.io/op-alloy/).
+
+## Contributing
+
+To build the book locally, a few dependencies are required:
+```sh
+cargo install mdbook mdbook-mermaid mdbook-template
+```
+
+Then, to run the book locally during development, run:
+```sh
+mdbook serve
+```

book/book.toml

@@ -0,0 +1,19 @@
+[book]
+authors = ["refcell"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The op-alloy Book"
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[preprocessor.template]
+
+[output.html]
+default-theme = "ferra"
+preferred-dark-theme = "ferra"
+git-repository-url = "https://github.com/alloy-rs/op-alloy"
+edit-url-template = "https://github.com/alloy-rs/op-alloy/edit/main/book/{path}"
+additional-css = ["custom.css"]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]

book/custom.css

@@ -0,0 +1,141 @@
+table {
+    width: 100%;
+}
+
+table thead th {
+    padding: .75rem;
+    text-align: left;
+    font-weight: 500;
+    line-height: 1.5;
+    width: auto;
+}
+
+table td {
+    padding: .75rem;
+    border: none;
+}
+
+table thead tr {
+    border: none;
+    border-bottom: 2px var(--table-border-color) solid;
+}
+
+table tbody tr {
+    border-bottom: 1px var(--table-border-line) solid;
+}
+
+table tbody tr:nth-child(2n) {
+    background: unset;
+}
+
+.content h1,
+.content h2,
+.content h3,
+.content h4 {
+    font-weight: 600;
+    margin-top: 1.275em;
+    margin-bottom: .875em;
+}
+
+.ferra {
+    --bg: #2b292d;
+    --fg: #fecdb2;
+    --heading-fg: #fff;
+
+    --sidebar-bg: #383539;
+    --sidebar-fg: #fecdb2;
+    --sidebar-non-existant: #feceb454;
+    --sidebar-active: #ffa07a;
+    --scrollbar: var(--sidebar-fg);
+
+    --icons: #f6b6c9ba;
+    --icons-hover: #b7b9cc;
+
+    --links: #ffa07a;
+
+    --inline-code-color: #f6b6c9ba;
+
+    --theme-popup-bg: #383539;
+    --theme-popup-border: #5f5a60;
+    --theme-hover: rgba(0, 0, 0, .2);
+
+    --quote-bg: #222124;
+    --quote-border: #2b292d;
+
+    --table-border-color: #383539;
+    --table-header-bg: hsla(226, 23%, 31%, 0);
+    --table-alternate-bg: hsl(226, 23%, 14%);
+    --table-border-line: #383539;
+
+    --searchbar-border-color: #222124;
+    --searchbar-bg: #222124;
+    --searchbar-fg: #fecdb2;
+    --searchbar-shadow-color: #aaa;
+    --searchresults-header-fg: #fce2d4;
+    --searchresults-border-color: #feceb454;
+    --search-mark-bg: #f6b6c9ba;
+
+}
+
+.ferra .content .header {
+    color: #fce2d4;
+}
+
+/* highlight.js theme, :where() is used to avoid increasing specificity */
+
+:where(.ferra) .hljs {
+    background: #222124;
+    color: #feceb4e1;
+}
+
+:where(.ferra) .hljs-comment,
+:where(.ferra) .hljs-quote {
+    color: #6F5D63;
+}
+
+:where(.ferra) .hljs-link,
+:where(.ferra) .hljs-meta,
+:where(.ferra) .hljs-name,
+:where(.ferra) .hljs-regexp,
+:where(.ferra) .hljs-selector-class,
+:where(.ferra) .hljs-selector-id,
+:where(.ferra) .hljs-tag,
+:where(.ferra) .hljs-template-variable,
+:where(.ferra) .hljs-variable {
+    color: #fecdb2;
+}
+
+:where(.ferra) .hljs-built_in,
+:where(.ferra) .hljs-deletion,
+:where(.ferra) .hljs-literal,
+:where(.ferra) .hljs-number,
+:where(.ferra) .hljs-params,
+:where(.ferra) .hljs-type {
+    color: #f6b6c9;
+}
+
+:where(.ferra) .hljs-attribute,
+:where(.ferra) .hljs-section,
+:where(.ferra) .hljs-title {
+    color: #ffa07a;
+}
+
+:where(.ferra) .hljs-addition,
+:where(.ferra) .hljs-bullet,
+:where(.ferra) .hljs-string,
+:where(.ferra) .hljs-symbol {
+    color: #b1b695;
+}
+
+:where(.ferra) .hljs-keyword,
+:where(.ferra) .hljs-selector-tag {
+    color: #d1d1e0;
+}
+
+:where(.ferra) .hljs-emphasis {
+    font-style: italic;
+}
+
+:where(.ferra) .hljs-strong {
+    font-weight: 700;
+}

book/mermaid-init.js

@@ -0,0 +1 @@
+mermaid.initialize({ startOnLoad: true, theme: 'dark' });

book/src/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thank you for wanting to contribute! Before contributing to this repository, please read through this document and
+discuss the change you wish to make via issue.
+
+## Dependencies
+
+Before working with this repository locally, you'll need to install several dependencies:
+
+- [Docker](https://www.docker.com/) for cross-compilation.
+- [just](https://github.com/casey/just) for our command-runner scripts.
+- The [Rust toolchain](https://rustup.rs/)
+- The [Golang toolchain](https://go.dev/dl/)
+
+**Optional**
+
+- [mdbook](https://github.com/rust-lang/mdBook) to contribute to the [book](/)
+  - [mdbook-template](https://github.com/sgoudham/mdbook-template)
+  - [mdbook-mermaid](https://github.com/badboy/mdbook-mermaid)
+
+## Pull Request Process
+
+1. Before anything, [create an issue](https://github.com/alloy-rs/op-alloy/issues/new) to discuss the change you're
+   wanting to make, if it is significant or changes functionality. Feel free to skip this step for trivial changes.
+1. Once your change is implemented, ensure that all checks are passing before creating a PR. The full CI pipeline can
+   be run locally via the `Justfile`s in the repository.
+1. Make sure to update any documentation that has gone stale as a result of the change, in the `README` files, the [book][book],
+   and in rustdoc comments.
+1. Once you have sign-off from a maintainer, you may merge your pull request yourself if you have permissions to do so.
+   If not, the maintainer who approves your pull request will add it to the merge queue.

book/src/SUMMARY.md

@@ -0,0 +1,5 @@
+# Summary
+
+- [Introduction](./intro.md)
+- [Glossary](./glossary.md)
+- [Contributing](./CONTRIBUTING.md)

book/src/glossary.md

@@ -0,0 +1,5 @@
+# Glossary
+
+*This document contains definitions for terms used throughout the op-alloy book.*
+
+

book/src/intro.md

@@ -0,0 +1,27 @@
+# op-alloy Book
+
+_Documentation for op-alloy._
+
+<a href="https://github.com/alloy-rs/op-alloy"><img src="https://img.shields.io/badge/GitHub%20Repo-op-alloy-green?logo=github"></a>
+
+> 📖 `op-alloy` is in active development, and is not yet ready for use in production. During development, this book will evolve quickly and may contain inaccuracies.
+>
+> Please [open an issue][new-issue] if you find any errors or have any suggestions for improvements, and also feel free to [contribute][contributing] to the project!
+
+## Introduction
+
+op-alloy is a collection of types, middleware, and networks for Optimism built on top of [alloy][alloy].
+
+It is built and maintained by Alloy contributors, members of [OP Labs][op-labs], and the broader
+open source community. op-alloy is licensed under the combined Apache 2.0 and MIT License, along
+with a SNAPPY license for snappy encoding use.
+
+## Development Status
+
+**op-alloy is currently in active development, and is not yet ready for use in production.**
+
+## Contributing
+
+Contributors are welcome! Please see the [contributing guide][contributing] for more information.
+
+{{#include ./links.md}}

book/src/links.md

@@ -0,0 +1,31 @@
+<!-- External -->
+
+[op-stack]: https://github.com/ethereum-optimism/optimism
+[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program
+[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon
+[cannon-rs]: https://github.com/anton-rs/cannon-rs
+[asterisc]: https://github.com/ethereum-optimism/asterisc
+[fp-specs]: https://specs.optimism.io/experimental/fault-proof/index.html
+[fpp-specs]: https://specs.optimism.io/experimental/fault-proof/index.html#fault-proof-program
+[preimage-specs]: https://specs.optimism.io/experimental/fault-proof/index.html#pre-image-oracle
+[cannon-specs]: https://specs.optimism.io/experimental/fault-proof/cannon-fault-proof-vm.html#cannon-fault-proof-virtual-machine
+[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction
+[op-succinct]: https://github.com/succinctlabs/op-succinct
+[revm]: https://github.com/bluealloy/revm
+
+<!-- Alloy -->
+
+[alloy]: https://github.com/alloy-rs/alloy
+
+<!-- Kona links -->
+
+[kona]: https://github.com/anton-rs/kona
+[book]: https://anton-rs.github.io/kona/
+[issues]: https://github.com/anton-rs/kona/issues
+[new-issue]: https://github.com/anton-rs/kona/issues/new
+[contributing]: https://github.com/anton-rs/kona/tree/main/CONTRIBUTING.md
+
+<!-- People -->
+
+[op-labs]: https://github.com/ethereum-optimism
+[bad-boi-labs]: https://github.com/BadBoiLabs

book/templates/glossary-link.md

@@ -0,0 +1 @@
+[[[ #text ]]]([[ #root ]]glossary.md#[[ #ref ]])