Migrate docs to docusaurus

.github/workflows/build-docs.yml

@@ -0,0 +1,46 @@
+name: build-docs
+
+# Limits workflow concurrency to only the latest commit in the PR.
+concurrency:
+  group: "${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}"
+  cancel-in-progress: true
+
+on:
+  push:
+    branches: [main, next]
+    paths:
+      - "docs/**"
+      - ".github/workflows/build-docs.yml"
+  pull_request:
+    types: [opened, reopened, synchronize]
+    paths:
+      - "docs/**"
+      - ".github/workflows/build-docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-docs:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: ./docs
+        run: npm ci
+
+      - name: Build documentation
+        working-directory: ./docs
+        run: npm run build:dev

.github/workflows/trigger-deploy-docs.yml

@@ -0,0 +1,21 @@
+name: Trigger Aggregator Docs Rebuild
+
+on:
+  push:
+    branches: [next]
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Send repository_dispatch to aggregator
+        uses: peter-evans/repository-dispatch@a628c95fd17070f003ea24579a56e6bc89b25766
+        with:
+          # PAT that can access the central aggregator repository
+          token: ${{ secrets.DOCS_REPO_TOKEN }}
+          repository: ${{ vars.DOCS_AGGREGATOR_REPO }}
+          event-type: rebuild

Makefile

@@ -68,9 +68,9 @@ doc: ## Generates & checks documentation
 	$(WARNINGS) cargo doc --all-features --keep-going --release
 
 
-.PHONY: book
-book: ## Builds the book & serves documentation site
-	mdbook serve --open docs
+.PHONY: serve-docs
+serve-docs: ## Serves the docs
+	cd docs && npm run start:dev
 
 # --- testing -------------------------------------------------------------------------------------
 
@@ -139,16 +139,22 @@ bench-note-checker: ## Run note checker benchmarks
 .PHONY: check-tools
 check-tools: ## Checks if development tools are installed
 	@echo "Checking development tools..."
-	@command -v mdbook >/dev/null 2>&1 && echo "[OK] mdbook is installed" || echo "[MISSING] mdbook is not installed (run: make install-tools)"
+	@command -v npm >/dev/null 2>&1 && echo "[OK] npm is installed" || echo "[MISSING] npm is not installed (run: make install-tools)"
 	@command -v typos >/dev/null 2>&1 && echo "[OK] typos is installed" || echo "[MISSING] typos is not installed (run: make install-tools)"
 	@command -v cargo nextest >/dev/null 2>&1 && echo "[OK] cargo-nextest is installed" || echo "[MISSING] cargo-nextest is not installed (run: make install-tools)"
 	@command -v taplo >/dev/null 2>&1 && echo "[OK] taplo is installed" || echo "[MISSING] taplo is not installed (run: make install-tools)"
 	@command -v cargo-machete >/dev/null 2>&1 && echo "[OK] cargo-machete is installed" || echo "[MISSING] cargo-machete is not installed (run: make install-tools)"
 
 .PHONY: install-tools
 install-tools: ## Installs development tools required by the Makefile (mdbook, typos, nextest, taplo)
-	@echo "Installing development tools..."
-	cargo install mdbook --locked
+	@echo "Installing development tools...""
+	@if ! command -v node >/dev/null 2>&1; then \
+		echo "Node.js not found. Please install Node.js from https://nodejs.org/ or using your package manager"; \
+		echo "On macOS: brew install node"; \
+		echo "On Ubuntu/Debian: sudo apt install nodejs npm"; \
+		echo "On Windows: Download from https://nodejs.org/"; \
+		exit 1; \
+	fi
 	cargo install typos-cli --locked
 	cargo install cargo-nextest --locked
 	cargo install taplo-cli --locked

README.md

@@ -16,10 +16,10 @@ Miden is a zero-knowledge rollup for high-throughput and private applications. M
 
 If you want to join the technical discussion or learn more about the project, please check out
 
-* the [Documentation](https://0xMiden.github.io/miden-docs).
-* the [Telegram](https://t.me/BuildOnMiden)
-* the [Repo](https://github.com/0xMiden)
-* the [Roadmap](https://miden.xyz/roadmap)
+- the [Documentation](https://0xMiden.github.io/miden-docs).
+- the [Telegram](https://t.me/BuildOnMiden)
+- the [Repo](https://github.com/0xMiden)
+- the [Roadmap](https://miden.xyz/roadmap)
 
 ## Status and features
 
@@ -44,12 +44,12 @@ Miden is currently on release v0.12. This is an early version of the protocol an
 
 ## Project structure
 
-| Crate                                                          | Description                                                                         |
-|----------------------------------------------------------------|-------------------------------------------------------------------------------------|
-| [objects](crates/miden-objects)                                | Contains core components defining the Miden rollup protocol.                        |
-| [miden-lib](crates/miden-lib)                                  | Contains the code of the Miden rollup kernels and standardized smart contracts.     |
-| [miden-tx](crates/miden-tx)                                    | Contains tool for creating, executing, and proving Miden rollup transaction.        |
-| [bench-tx](bin/bench-tx)                                       | Contains transaction execution and proving benchmarks.                              |
+| Crate                           | Description                                                                     |
+| ------------------------------- | ------------------------------------------------------------------------------- |
+| [objects](crates/miden-objects) | Contains core components defining the Miden rollup protocol.                    |
+| [miden-lib](crates/miden-lib)   | Contains the code of the Miden rollup kernels and standardized smart contracts. |
+| [miden-tx](crates/miden-tx)     | Contains tool for creating, executing, and proving Miden rollup transaction.    |
+| [bench-tx](bin/bench-tx)        | Contains transaction execution and proving benchmarks.                          |
 
 ## Make commands
 
@@ -69,6 +69,10 @@ make test
 
 Some of the functions in this project are computationally intensive and may take a significant amount of time to compile and complete during testing. To ensure optimal results we use the `make test` command. It enables the running of tests in release mode and using specific configurations replicates the test conditions of the development mode and verifies all debug assertions.
 
+## Documentation
+
+The documentation in the `docs/` folder is built using Docusaurus and is automatically absorbed into the main [miden-docs](https://github.com/0xMiden/miden-docs) repository for the main documentation website. Changes to the `next` branch trigger an automated deployment workflow. The docs folder requires npm packages to be installed before building.
+
 ## License
 
 This project is [MIT licensed](./LICENSE)

docs/.gitignore

@@ -1 +1,3 @@
-book
+.docusaurus/
+build/
+node_modules/

docs/docusaurus.config.ts

@@ -0,0 +1,129 @@
+import type { Config } from "@docusaurus/types";
+import { themes as prismThemes } from "prism-react-renderer";
+
+// If your content lives in docs/src, set DOCS_PATH='src'; else '.'
+const DOCS_PATH =
+  process.env.DOCS_PATH || (require("fs").existsSync("src") ? "src" : ".");
+
+const config: Config = {
+  title: "Docs Dev Preview",
+  url: "http://localhost:3000",
+  baseUrl: "/",
+  trailingSlash: false,
+
+  // Minimal classic preset: docs only, autogenerated sidebars, same math plugins as prod
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          path: DOCS_PATH, // '../docs' is implied because we are already inside docs/
+          routeBasePath: "/", // mount docs at root for quick preview
+          sidebarPath: "./sidebars.ts",
+          remarkPlugins: [require("remark-math")],
+          rehypePlugins: [require("rehype-katex")],
+          versions: {
+            current: {
+              label: `unstable`,
+            },
+          },
+        },
+        blog: false,
+        pages: false,
+        theme: {
+          customCss: "./styles.css",
+        },
+      },
+    ],
+  ],
+
+  plugins: [
+    [
+      "@cmfcmf/docusaurus-search-local",
+      {
+        // whether to index docs pages
+        indexDocs: true,
+
+        // whether to index blog pages
+        indexBlog: false,
+
+        // whether to index static pages
+        indexPages: false,
+
+        // language of your documentation, see next section
+        language: "en",
+
+        // setting this to "none" will prevent the default CSS to be included. The default CSS
+        // comes from autocomplete-theme-classic, which you can read more about here:
+        // https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-theme-classic/
+        style: undefined,
+
+        // lunr.js-specific settings
+        lunr: {
+          // When indexing your documents, their content is split into "tokens".
+          // Text entered into the search box is also tokenized.
+          // This setting configures the separator used to determine where to split the text into tokens.
+          // By default, it splits the text at whitespace and dashes.
+          //
+          // Note: Does not work for "ja" and "th" languages, since these use a different tokenizer.
+          tokenizerSeparator: /[\s\-]+/,
+          // https://lunrjs.com/guides/customising.html#similarity-tuning
+          //
+          // This parameter controls the importance given to the length of a document and its fields. This
+          // value must be between 0 and 1, and by default it has a value of 0.75. Reducing this value
+          // reduces the effect of different length documents on a term's importance to that document.
+          b: 0.75,
+          // This controls how quickly the boost given by a common word reaches saturation. Increasing it
+          // will slow down the rate of saturation and lower values result in quicker saturation. The
+          // default value is 1.2. If the collection of documents being indexed have high occurrences
+          // of words that are not covered by a stop word filter, these words can quickly dominate any
+          // similarity calculation. In these cases, this value can be reduced to get more balanced results.
+          k1: 1.2,
+          // By default, we rank pages where the search term appears in the title higher than pages where
+          // the search term appears in just the text. This is done by "boosting" title matches with a
+          // higher value than content matches. The concrete boosting behavior can be controlled by changing
+          // the following settings.
+          titleBoost: 5,
+          contentBoost: 1,
+          tagsBoost: 3,
+          parentCategoriesBoost: 2, // Only used when indexing is enabled for categories
+        },
+      },
+    ],
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    {
+      colorMode: {
+        defaultMode: "light",
+        disableSwitch: true,
+      },
+      prism: {
+        theme: prismThemes.oneLight,
+        darkTheme: prismThemes.oneDark,
+        additionalLanguages: ["rust", "solidity", "toml", "yaml"],
+      },
+      navbar: {
+        logo: {
+          src: "img/logo.png",
+          alt: "Miden Logo",
+          height: 240,
+        },
+        title: "MIDEN",
+        items: [
+          {
+            type: "docsVersionDropdown",
+            position: "left",
+            dropdownActiveClassDisabled: true,
+          },
+          {
+            href: "https://github.com/0xMiden/",
+            label: "GitHub",
+            position: "right",
+          },
+        ],
+      },
+    },
+};
+export default config;