Migrate docs from mdbook 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/external/**"
+      - ".github/workflows/build-docs.yml"
+  pull_request:
+    types: [opened, reopened, synchronize]
+    paths:
+      - "docs/external/**"
+      - ".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/external/package-lock.json
+
+      - name: Install dependencies
+        working-directory: ./docs/external
+        run: npm ci
+
+      - name: Build documentation
+        working-directory: ./docs/external
+        run: npm run build:dev

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

@@ -0,0 +1,23 @@
+name: Trigger Aggregator Docs Rebuild
+
+on:
+  push:
+    branches: [next]
+    paths:
+      - "docs/external/**"
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Send repository_dispatch to aggregator
+        uses: peter-evans/repository-dispatch@a628c95fd17070f003ea24579a56e6bc89b25766
+        with:
+          # PAT (Personal Access Token) that grants permission to trigger the rebuild workflow at the docs repository
+          token: ${{ secrets.DOCS_REPO_TOKEN }}
+          repository: ${{ vars.DOCS_AGGREGATOR_REPO }}
+          event-type: rebuild

Makefile.toml

@@ -331,11 +331,25 @@ description = "Set up the litcheck utility"
 install_crate = { crate_name = "litcheck", test_arg = "--help" }
 
 [tasks.docs]
+category = "Documentation"
+description = "Opens the public compiler documentation"
+dependencies = ["docusaurus"]
+cwd = "./docs/external"
+command = "npm"
+args = ["run", "start:dev"]
+
+[tasks.docusaurus]
 category = "Build"
-description = "Builds the compiler documentation"
+cwd = "./docs/external"
+command = "npm"
+args = ["install"]
+
+[tasks.internal-docs]
+category = "Documentation"
+description = "Builds the internal compiler documentation"
 dependencies = ["mdbook", "mdbook-linkcheck", "mdbook-alerts", "mdbook-katex"]
 command = "mdbook"
-args = ["build", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/docs"]
+args = ["build", "${CARGO_MAKE_WORKSPACE_WORKING_DIRECTORY}/docs/internal"]
 
 [tasks.mdbook]
 category = "Build"

README.md

@@ -1,6 +1,6 @@
 # Miden Compiler
 
-> [!IMPORTANT] 
+> [!IMPORTANT]
 > This project is a work-in-progress, so if you encounter bugs or other
 > things which are not covered in the issue tracker, there is a good chance we know
 > about them, but please do report them anyway so we can ensure they are tracked
@@ -12,18 +12,18 @@ or as means of compiling WebAssembly (Wasm) produced by another compiler to Mide
 
 This repo is broken into the following high-level components:
 
-* Miden HIR (high-level intermediate representation) and it's supporting crates;
-providing everything needed to build and compile IR for a program you want to
-emit Miden Assembly for.
-* The Wasm frontend; a library which can be used to convert a program compiled to `.wasm` to HIR
-* The `midenc` executable, which provides a command-line tool that provides a convenient way
-to compile Wasm or HIR modules/programs to Miden Assembly and test them.
+- Miden HIR (high-level intermediate representation) and it's supporting crates;
+  providing everything needed to build and compile IR for a program you want to
+  emit Miden Assembly for.
+- The Wasm frontend; a library which can be used to convert a program compiled to `.wasm` to HIR
+- The `midenc` executable, which provides a command-line tool that provides a convenient way
+  to compile Wasm or HIR modules/programs to Miden Assembly and test them.
 
-> [!TIP] 
-> We've published initial [documentation](https://0xMiden.github.io/compiler) 
-> in mdBook format for easier reading, also accessible in the `docs` directory. This documentation 
+> [!TIP]
+> We've published initial [documentation](https://0xMiden.github.io/compiler)
+> in mdBook format for easier reading, also accessible in the `docs` directory. This documentation
 > covers how to get started with the compiler, provides a couple guides for currently supported
-> use cases, and contains appendices that go into detail about various design aspects of the 
+> use cases, and contains appendices that go into detail about various design aspects of the
 > toolchain.
 
 ## Building
@@ -50,6 +50,12 @@ To run the compiler test suite:
 
 This will run all of the unit tests in the workspace, as well as all of our `lit` tests.
 
+## Docs
+
+The documentation in the `docs/external` 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.
+
+The `docs/internal` folder corresponds to internal docs, which are hosted using mdbook and Github Pages here: [0xmiden.github.io/compiler/](0xmiden.github.io/compiler/). These md files are not exported to the main docs.
+
 ## Packaging
 
 TBD

docs/external/.gitignore

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

docs/external/docusaurus.config.ts

@@ -0,0 +1,31 @@
+import type { Config } from "@docusaurus/types";
+
+// 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")],
+        },
+        blog: false,
+        pages: false,
+      },
+    ],
+  ],
+};
+export default config;