Merge pull request #127 from 0xMiden/chore/docusaurus-migration

Migrate docs from mdbook to docusaurus

Author: Keinberger

.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]
+    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,23 @@
+name: Trigger Aggregator Docs Rebuild
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+
+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

README.md

@@ -8,3 +8,9 @@ This repository is organized into several parts:
 2. **masm**, contains the Miden assembly notes, accounts, and scripts used in the examples.
 3. **rust-client**, contains examples for interacting with the Miden Rollup using **Rust**.
 4. **web-client**, contains examples for interacting with the Miden Rollup in the browser.
+
+## Documentation
+
+The documentation (tutorials) 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.
+
+The documentation folder is also a standalone Rust repository. The purpose of this is to be able to run `cargo doc test`, to test the Rust code inside of the tutorial markdowns.

docs/.gitignore

@@ -0,0 +1,3 @@
+.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: `stable`,
+            },
+          },
+        },
+        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;