chore: migrate to vocs

.github/workflows/deploy.yml

@@ -11,23 +11,18 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - name: Install mdbook-external-links
-        run: cargo install mdbook-external-links
-      - name: Install mdbook
-        run: |
-          mkdir mdbook
-          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
-
-      - name: Build book
-        run: mdbook build
+
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Build Vocs
+        run: cd vocs && bun install && bun run build
 
       - name: Publish
         uses: cloudflare/[email protected]
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           projectName: foundry-book
-          directory: book
+          directory: vocs/docs/dist
           gitHubToken: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -1,4 +1,4 @@
-name: test
+name: build
 on:
   push:
     branches: [master]
@@ -8,16 +8,14 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    name: mdbook test
+    name: vocs build
 
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
 
-      - name: Install mdbook
-        run: |
-          mkdir mdbook
-          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
-          echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Install bun
+        uses: oven-sh/setup-bun@v2
 
-      - name: Run tests
-        run: mdbook test
+      - name: Build Vocs
+        run: cd vocs && bun install && bun run build

.gitignore

@@ -3,6 +3,9 @@
 /.vscode
 
 /cache/
-/projects/**/cache/
+/vocs/snippets/projects/**/cache/
 /out/
-/projects/**/out/
+/vocs/snippets/projects/**/out/
+
+/vocs/node_modules
+/vocs/docs/dist

CONTRIBUTING.md

@@ -75,27 +75,27 @@ Each output file has three anchors you can use:
 **Display the command _and_ the output**
 
 ```handlebars
-{{#include ../output/abc/xyz:all}}
+// [!include ~/snippets/output/abc/xyz:all]
 ```
 
 **Display just the command**
 
 ```handlebars
-{{#include ../output/abc/xyz:command}}
+// [!include ~/snippets/output/abc/xyz:command]
 ```
 
 **Display just the output**
 
 ```handlebars
-{{#include ../output/abc/xyz:output}}
+// [!include ~/snippets/output/abc/xyz:output]
 ```
 
-You can learn more about auto-generated CLI output in the [output folder](./src/output).
+You can learn more about auto-generated CLI output in the [output folder](./vocs/docs/snippets/output).
 
 #### Where possible, do NOT in-line Solidity code
 
-In the same vein as the previous style guideline, opt to include source files, or parts of source files, from the [projects folder](./projects).
+In the same vein as the previous style guideline, opt to include source files, or parts of source files, from the [projects folder](./vocs/docs/snippets/projects).
 
 This allows us to quickly iterate and improve on our examples without having to change multiple pages.
 
-You can learn more about including files in the [mdbook documentation](https://rust-lang.github.io/mdBook/format/mdbook.html).
+Learn more about including snippets and files in the [vocs documentation](https://vocs.dev/docs/guides/code-snippets#physical-file-snippets).

README.md

@@ -12,23 +12,15 @@ A book on all things Foundry. [Read now](https://book.getfoundry.sh).
 
 Check our [contributing guidelines](./CONTRIBUTING.md). Feel free to contribute wording, sentences, chapters, and guides!
 
-The book is build with [mdbook](https://github.com/rust-lang/mdBook), which you can get by running `cargo install mdbook`.
-
-The book also requires [`mdbook-external-links`](https://github.com/jonahgoldwastaken/mdbook-external-links): `cargo install mdbook-external-links`.
+The book is built with [vocs](https://vocs.dev), which you can get by running `bun i vocs`.
 
 To see the book change live run:
 
 ```sh
-mdbook serve
-```
-
-To run the book with docker, run:
-
-```sh
-docker run -p 3000:3000 -v `pwd`:/book peaceiris/mdbook serve
+cd vocs && bun dev
 ```
 
-To add a new section (file) to the book, add it to [`SUMMARY.md`](src/SUMMARY.md).
+To add a new section (file) to the book, add it to [`sidebar.ts`](./vocs/sidebar/sidebar.ts).
 
 For a more structured overview of the current issues, see [the GitHub project](https://github.com/orgs/foundry-rs/projects/1).
 

scripts/common

@@ -6,7 +6,8 @@ set -eo pipefail
 # includeable in the book.
 
 ETH_RPC_URL="${ETH_RPC_URL:=https://eth-mainnet.alchemyapi.io/v2/Lc7oIGYeL_QvInzI0Wiu_pOZZDEKBrdf}"
-OUTPUT_DIR="$(realpath src/output)"
+SNIPPETS_DIR="$(realpath vocs/docs/snippets)"
+OUTPUT_DIR="$(realpath $SNIPPETS_DIR/output)"
 ROOT="$(dirname "$(dirname "$(realpath "$0")")")"
 # shellcheck disable=SC2034
 SCRIPTS="$ROOT/scripts"
@@ -43,14 +44,14 @@ escape_colors() {
 
 print_anchored() {
   cat > /dev/stdout <<EOF
-// ANCHOR: all
-// ANCHOR: command
+// [!region all]
+// [!region command]
 \$ $1
-// ANCHOR_END: command
-// ANCHOR: output
+// [!endregion command]
+// [!region output]
 $2
-// ANCHOR_END: output
-// ANCHOR_END: all
+// [!endregion output]
+// [!endregion all]
 EOF
 }
 
@@ -59,8 +60,8 @@ EOF
 # The project must live in ./projects
 in_project() {
   echo "... $1"
-  mkdir -p "$OUTPUT_DIR/$1"
-  cd "$ROOT/projects/$1"
+  mkdir -p "$OUTPUT_DIR/projects/$1"
+  cd "$SNIPPETS_DIR/projects/$1"
   forge clean
 }
 

scripts/gen_output/cast.sh

@@ -13,7 +13,7 @@ gen_cast() {
     cast call 0x6b175474e89094c44da98b954eedeac495271d0f "totalSupply()(uint256)" --rpc-url "$ETH_RPC_URL"
 
   run_command "$OUTPUT_DIR/cast/cast-4byte-calldata" \
-    cast 4byte-calldata 0x1F1F897F676d00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003e7 \
+    cast 4byte-decode 0x1F1F897F676d00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003e7 \
 
   echo OK.
 }

scripts/gen_output/chisel.sh

@@ -6,6 +6,8 @@ gen_chisel() {
 
   echo "Generating output (chisel)..."
 
+  mkdir -p "$OUTPUT_DIR/chisel"
+
   print_anchored \
     "echo '!help' | chisel" \
     "$(echo '!help' | chisel | escape_colors)" \

scripts/gen_output/help.rs

@@ -22,13 +22,14 @@ use std::{fmt, process};
 
 const SECTION_START: &str = "<!-- CLI_REFERENCE START -->";
 const SECTION_END: &str = "<!-- CLI_REFERENCE END -->";
-const README: &str = r#"# CLI Reference
+const README: &str = r#"import Summary from './SUMMARY.mdx';
+# CLI Reference
 
 <!-- Generated by scripts/gen_output/help.rs -->
 
 Automatically-generated CLI reference from `--help` output.
 
-{{#include ./SUMMARY.md}}
+<Summary />
 "#;
 const TRIM_LINE_END_MARKDOWN: bool = false;
 
@@ -49,7 +50,7 @@ struct Args {
     #[arg(long, default_value = ".")]
     root_dir: PathBuf,
 
-    /// Indentation for the root SUMMARY.md file
+    /// Indentation for the root SUMMARY.mdx file
     #[arg(long, default_value = "2")]
     root_indentation: usize,
 
@@ -61,7 +62,7 @@ struct Args {
     #[arg(long)]
     readme: bool,
 
-    /// Whether to update the root SUMMARY.md file
+    /// Whether to update the root SUMMARY.mdx file
     #[arg(long)]
     root_summary: bool,
 
@@ -127,14 +128,14 @@ fn main() -> io::Result<()> {
         cmd_markdown(&out_dir, cmd, stdout)?;
     }
 
-    // Generate SUMMARY.md.
+    // Generate SUMMARY.mdx.
     let summary: String = output
         .iter()
         .map(|(cmd, _)| cmd_summary(None, cmd, 0))
         .chain(once("\n".to_string()))
         .collect();
 
-    write_file(&out_dir.clone().join("SUMMARY.md"), &summary)?;
+    write_file(&out_dir.clone().join("SUMMARY.mdx"), &summary)?;
 
     // Generate README.md.
     if args.readme {
@@ -145,7 +146,7 @@ fn main() -> io::Result<()> {
         write_file(path, README)?;
     }
 
-    // Generate root SUMMARY.md.
+    // Generate root SUMMARY.mdx.
     if args.root_summary {
         let root_summary: String = output
             .iter()
@@ -256,9 +257,9 @@ fn cmd_summary(md_root: Option<PathBuf>, cmd: &Cmd, indent: usize) -> String {
     format!("{indent_string}- [`{cmd}`](./{full_cmd_path}.md)\n")
 }
 
-/// Replaces the CLI_REFERENCE section in the root SUMMARY.md file.
+/// Replaces the CLI_REFERENCE section in the root SUMMARY.mdx file.
 fn update_root_summary(root_dir: &Path, root_summary: &str) -> io::Result<()> {
-    let summary_file = root_dir.join("SUMMARY.md");
+    let summary_file = root_dir.join("SUMMARY.mdx");
     let original_summary_content = fs::read_to_string(&summary_file)?;
 
     let section_re = regex!(&format!(r"(?s)\s*{SECTION_START}.*?{SECTION_END}"));