docusaurus.config.ts

import type { Config } from "@docusaurus/types";
import { themes as prismThemes } from "prism-react-renderer";
import remarkMath from "remark-math";
import rehypeKatex from "rehype-katex";
import { readFileSync } from "fs";
import { parse as parseYaml } from "yaml";
import { join } from "path";

// Read the next version from release manifest
const releaseManifestPath = join(__dirname, ".release", "release-manifest.yml");
const releaseManifest = parseYaml(readFileSync(releaseManifestPath, "utf8"));
const nextVersion = releaseManifest.next_version;

const config: Config = {
  title: "Miden Docs",
  tagline: "One stop shop for everything Miden",
  favicon: "img/favicon.ico",

  url: "https://docs.miden.xyz/",
  baseUrl: "",

  organizationName: "0xMiden",
  projectName: "docs",

  onBrokenLinks: "warn",
  onBrokenMarkdownLinks: "warn",

  i18n: {
    defaultLocale: "en",
    locales: ["en"],
  },

  headTags: [
    {
      tagName: "meta",
      attributes: {
        name: "algolia-site-verification",
        content: "6DD254F2A01D1F58",
      },
    },
  ],

  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      {
        docs: {
          // Single global docs root
          routeBasePath: "/", // site lives at /
          sidebarPath: "./sidebars.ts", // use autogenerated,
          includeCurrentVersion: true,
          versions: {
            current: {
              label: `${nextVersion} (unstable)`,
            },
          },
          remarkPlugins: [remarkMath],
          rehypePlugins: [rehypeKatex],
        }, // Disable preset docs plugin => using own plugin
        blog: false, // Disable blog
        theme: {
          customCss: "./src/custom/styles.css",
        },
      },
    ],
  ],

  // enable mermaid diagrams and math support
  markdown: {
    mermaid: true,
  },

  stylesheets: [
    {
      href: "https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css",
      type: "text/css",
      integrity:
        "sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM",
      crossorigin: "anonymous",
    },
  ],

  themes: ["@docusaurus/theme-mermaid"],

  plugins: [
    [
      "@docusaurus/plugin-client-redirects",
      {
        // Use createRedirects for v0.12 → v0.13 path migrations
        // This ensures redirects are only created for paths that exist
        createRedirects(existingPath: string) {
          const redirects: string[] = [];

          // Builder section: redirect old root-level paths to new /builder/ paths
          if (existingPath === "/builder" || existingPath === "/builder/") {
            redirects.push("/intro");
          }
          if (existingPath.startsWith("/builder/get-started")) {
            redirects.push(existingPath.replace("/builder/get-started", "/quick-start"));
            redirects.push(existingPath.replace("/builder/get-started", "/builder/quick-start"));
          }
          if (existingPath === "/builder/faq") {
            redirects.push("/faq");
          }
          if (existingPath === "/builder/glossary") {
            redirects.push("/glossary");
          }
          if (existingPath.startsWith("/builder/tutorials/miden-bank")) {
            redirects.push(existingPath.replace("/builder/tutorials/miden-bank", "/builder/tutorials/rust-compiler/miden-bank"));
            redirects.push(existingPath.replace("/builder/tutorials/miden-bank", "/builder/develop/tutorials/rust-compiler/miden-bank"));
          }
          if (existingPath.startsWith("/builder/tutorials")) {
            redirects.push(existingPath.replace("/builder/tutorials", "/miden-tutorials"));
          }
          // Legacy redirect: old develop/tutorials paths
          if (existingPath.startsWith("/builder/develop/tutorials")) {
            redirects.push(existingPath.replace("/builder/develop/tutorials", "/miden-tutorials"));
          }
          if (existingPath.startsWith("/builder/tools")) {
            redirects.push(existingPath.replace("/builder/tools", "/miden-client"));
          }
          // Redirect old client path to new clients path
          if (existingPath.startsWith("/builder/tools/clients")) {
            redirects.push(existingPath.replace("/builder/tools/clients", "/builder/tools/client"));
          }

          // Core Concepts section: redirect old root-level paths to new /core-concepts/ paths
          if (existingPath.startsWith("/core-concepts/protocol")) {
            redirects.push(existingPath.replace("/core-concepts/protocol", "/miden-base"));
            // Also redirect old nested path
            redirects.push(existingPath.replace("/core-concepts/protocol", "/core-concepts/miden-base"));
          }
          if (existingPath.startsWith("/core-concepts/miden-vm")) {
            redirects.push(existingPath.replace("/core-concepts/miden-vm", "/miden-vm"));
          }
          if (existingPath.startsWith("/core-concepts/compiler")) {
            redirects.push(existingPath.replace("/core-concepts/compiler", "/compiler"));
          }
          if (existingPath.startsWith("/core-concepts/node")) {
            redirects.push(existingPath.replace("/core-concepts/node", "/miden-node"));
            // Also redirect old nested path
            redirects.push(existingPath.replace("/core-concepts/node", "/core-concepts/miden-node"));
          }

          // Redirect old /design/ paths to /core-concepts/
          if (existingPath.startsWith("/core-concepts")) {
            redirects.push(existingPath.replace("/core-concepts", "/design"));
          }

          return redirects.length > 0 ? redirects : undefined;
        },
      },
    ],
    [
      "@cmfcmf/docusaurus-search-local",
      {
        indexDocs: true,
        indexBlog: false,
        indexPages: false,
        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
        },
      },
    ],
  ],

  scripts: [
    {
      src: "https://scripts.simpleanalyticscdn.com/latest.js",
      async: true,
      defer: true,
      "data-hostname": "docs.miden.xyz",
    },
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    {
      image: "img/socialgraph_twitter.png",
      metadata: [
        { name: "twitter:card", content: "summary_large_image" },
        { name: "twitter:site", content: "@0xMiden" },
      ],
      mermaid: {
        theme: { light: "neutral", dark: "dark" },
        options: {
          fontFamily: '"Geist", ui-sans-serif, system-ui, sans-serif',
          fontSize: 14,
        },
      },
      colorMode: {
        defaultMode: "light",
        disableSwitch: false,
      },
      // TODO: implement exact code theme styling
      prism: {
        theme: prismThemes.oneLight,
        darkTheme: prismThemes.oneDark,
        additionalLanguages: [
          "rust",
          "solidity",
          "toml",
          "yaml",
          "diff",
          "bash",
          "shell-session",
          "docker",
          "ignore",
          "json",
          "json5",
        ],
      },
      navbar: {
        logo: {
          src: "img/logo.svg",
          alt: "Miden Logo",
          height: 32,
        },
        title: "MIDEN",
        items: [
          // LEFT - Section tabs using docSidebar
          {
            type: "docSidebar",
            sidebarId: "builderSidebar",
            label: "Build",
            position: "left",
          },
          {
            type: "docSidebar",
            sidebarId: "coreConceptsSidebar",
            label: "Core Concepts",
            position: "left",
          },

          // RIGHT - Social icons
          {
            type: "html",
            position: "right",
            value:
              '<a href="https://x.com/0xMiden" target="_blank" rel="noopener noreferrer" class="navbar-icon-link" aria-label="X (Twitter)"><svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z"/></svg></a>',
          },
          {
            type: "html",
            position: "right",
            value:
              '<a href="https://t.me/BuildOnMiden" target="_blank" rel="noopener noreferrer" class="navbar-icon-link" aria-label="Telegram"><svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><path d="M11.944 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0a12 12 0 0 0-.056 0zm4.962 7.224c.1-.002.321.023.465.14a.506.506 0 0 1 .171.325c.016.093.036.306.02.472-.18 1.898-.962 6.502-1.36 8.627-.168.9-.499 1.201-.82 1.23-.696.065-1.225-.46-1.9-.902-1.056-.693-1.653-1.124-2.678-1.8-1.185-.78-.417-1.21.258-1.91.177-.184 3.247-2.977 3.307-3.23.007-.032.014-.15-.056-.212s-.174-.041-.249-.024c-.106.024-1.793 1.14-5.061 3.345-.48.33-.913.49-1.302.48-.428-.008-1.252-.241-1.865-.44-.752-.245-1.349-.374-1.297-.789.027-.216.325-.437.893-.663 3.498-1.524 5.83-2.529 6.998-3.014 3.332-1.386 4.025-1.627 4.476-1.635z"/></svg></a>',
          },
          {
            type: "html",
            position: "right",
            value:
              '<a href="https://github.com/0xMiden/" target="_blank" rel="noopener noreferrer" class="navbar-icon-link" aria-label="GitHub"><svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/></svg></a>',
          },

          // Version dropdown
          {
            type: "docsVersionDropdown",
            position: "right",
            dropdownActiveClassDisabled: true,
          },

          // Search bar
          { type: "search", position: "right" },

          // Primary CTA
          {
            type: "html",
            position: "right",
            value:
              '<a class="navbar-cta" href="/builder/get-started"><span class="navbar-cta__label">Start building</span><span class="navbar-cta__arrow" aria-hidden="true">→</span></a>',
          },
        ],
      },
      footer: {
        style: "light",
        logo: {
          src: "img/logo.svg",
          alt: "Miden",
          height: 28,
        },
        links: [
          {
            title: "Build",
            items: [
              { label: "Get started", to: "/builder/get-started" },
              { label: "Smart contracts", to: "/builder/smart-contracts" },
              { label: "Tutorials", to: "/builder/tutorials/rust-compiler" },
              { label: "Tools", to: "/builder/tools" },
              { label: "Migration", to: "/builder/migration" },
            ],
          },
          {
            title: "Concepts",
            items: [
              { label: "Overview", to: "/core-concepts" },
              { label: "Protocol", to: "/core-concepts/protocol" },
              { label: "Miden VM", to: "/core-concepts/miden-vm" },
              { label: "Compiler", to: "/core-concepts/compiler" },
              { label: "Node", to: "/core-concepts/node" },
            ],
          },
          {
            title: "Community",
            items: [
              { label: "GitHub", href: "https://github.com/0xMiden" },
              { label: "X", href: "https://x.com/0xMiden" },
              { label: "Telegram", href: "https://t.me/BuildOnMiden" },
              { label: "Forum", href: "https://github.com/0xMiden/miden-node/discussions" },
              { label: "Brand kit", href: "https://miden.xyz/brand" },
            ],
          },
          {
            title: "Resources",
            items: [
              { label: "Glossary", to: "/builder/glossary" },
              { label: "FAQ", to: "/builder/faq" },
              { label: "Playground", href: "https://playground.miden.xyz" },
              { label: "Explorer", href: "https://testnet.midenscan.com" },
              { label: "miden.xyz", href: "https://miden.xyz" },
            ],
          },
        ],
        copyright: `<span class="footer__tagline">Private by design · Verifiable by default</span><span class="footer__sep">·</span>© ${new Date().getFullYear()} Miden`,
      },
    },
};

export default config;