feat: docusaurus migration (#6533)

* chore: remove mkdocs specifics

* chore: migrate to docusaurus

* chore: update docs/pages/tools/flamegraphs.md

Co-authored-by: Matthew Keil <me@matthewkeil.com>

* chore: update packages/cli/docsgen/markdown.ts

Co-authored-by: Matthew Keil <me@matthewkeil.com>

* chore: update docs/src/css/custom.css

Co-authored-by: Phil Ngo <58080811+philknows@users.noreply.github.com>

* update docs/src/css/custom.css

Co-authored-by: Phil Ngo <58080811+philknows@users.noreply.github.com>

* chore: address comments

* chore: fix small issues

---------

Co-authored-by: Matthew Keil <me@matthewkeil.com>
Co-authored-by: Phil Ngo <58080811+philknows@users.noreply.github.com>

.github/workflows/docs.yml

@@ -64,19 +64,13 @@ jobs:
 
       - name: Set up Python
         uses: actions/setup-python@v1
-
-      - name: Install dependencies
-        working-directory: docs
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
 
       - name: Build docs
         working-directory: docs
-        run: mkdocs build --verbose --clean --site-dir site
+        run: yarn && yarn build
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/site
+          publish_dir: ./docs/build

.gitignore

@@ -48,7 +48,9 @@ docs/pages/lightclient-prover/lightclient.md
 docs/pages/lightclient-prover/prover.md
 docs/pages/api/api-reference.md
 docs/pages/contribution/getting-started.md
-docs/site
+## Docusaurus
+docs/.docusaurus/
+docs/build/
 
 # Testnet artifacts
 .lodestar
@@ -76,4 +78,4 @@ packages/cli/.git-data.json
 .last_build_unixsec
 dictionary.dic
 
-temp/
+temp/

.wordlist.txt

@@ -18,6 +18,7 @@ DVs
 Discv
 DockerHub
 Dockerized
+Docusaurus
 EIP
 EIPs
 EL
@@ -39,6 +40,7 @@ Geth
 Github
 Gossipsub
 Grafana
+HTTPS
 HackMD
 Homebrew
 IPFS
@@ -91,6 +93,7 @@ api
 async
 backfill
 beaconcha
+blockRoot
 blockchain
 bootnode
 bootnodes

docs/README.md

@@ -0,0 +1,25 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docusaurus.config.ts

@@ -0,0 +1,109 @@
+// There are various equivalent ways to declare your Docusaurus config.
+// See: https://docusaurus.io/docs/api/docusaurus-config
+
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+import {themes as prismThemes} from "prism-react-renderer";
+
+const config: Config = {
+  title: "Lodestar",
+  tagline: "TypeScript Implementation of Ethereum Consensus",
+  favicon: "img/favicon.ico",
+
+  // Set the production url of your site here
+  url: "https://chainsafe.github.io/",
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: "/lodestar/",
+
+  // GitHub pages deployment config.
+  organizationName: "ChainSafe",
+  projectName: "lodestar",
+
+  onBrokenLinks: "warn",
+  onBrokenMarkdownLinks: "warn",
+
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en"],
+  },
+
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          path: "pages",
+          sidebarPath: "./sidebars.ts",
+          editUrl: "https://github.com/ChainSafe/lodestar/tree/unstable/docs/",
+          routeBasePath: "/",
+        },
+        theme: {
+          customCss: "./src/css/custom.css",
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  markdown: {
+    mermaid: true,
+  },
+  themes: [
+    '@docusaurus/theme-mermaid',
+    ['@easyops-cn/docusaurus-search-local',
+     {"docsRouteBasePath": '/'}]
+  ],
+
+  themeConfig:
+    {
+      navbar: {
+        title: "Lodestar Documentation",
+        logo: {
+          alt: "Lodestar Logo",
+          src: "img/logo.png",
+        },
+        items: [
+          {
+            href: "https://github.com/ChainSafe/lodestar",
+            label: "GitHub",
+            position: "right",
+          },
+        ],
+      },
+      footer: {
+        style: "dark",
+        links: [
+          {
+            title: "Docs",
+            items: [
+              {
+                label: "Introduction",
+                to: "/introduction",
+              },
+            ],
+          },
+          {
+            title: "Community",
+            items: [
+              {
+                label: "Discord",
+                href: "https://discord.com/invite/yjyvFRP",
+              },
+              {
+                label: "Twitter",
+                href: "https://twitter.com/lodestar_eth",
+              },
+            ],
+          },
+        ],
+        copyright: `Copyright © ${new Date().getFullYear()} ChainSafe, Inc.`,
+      },
+      prism: {
+        additionalLanguages: ['bash', 'diff', 'json'],
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula,
+      },
+    } satisfies Preset.ThemeConfig,
+};
+
+export default config;

docs/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lodestar/docs",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids"
+  },
+  "dependencies": {
+    "@docusaurus/core": "3.1.1",
+    "@docusaurus/preset-classic": "3.1.1",
+    "@docusaurus/theme-mermaid": "^3.1.1",
+    "@easyops-cn/docusaurus-search-local": "^0.40.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.1.1",
+    "@docusaurus/types": "3.1.1"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}