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

@@ -328,11 +328,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,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;