Migrate docs to docusaurus

.github/workflows/deploy.yaml

@@ -1,59 +1,53 @@
-name: Deploy specification
+name: Deploy to GitHub Pages
 
 on:
   push:
     branches:
       - main
-
-env:
-  # this avoids node running out of memory while building
-  NODE_OPTIONS: --max_old_space_size=20480
+  workflow_dispatch:
 
 jobs:
-  deploy-spec:
+  build:
+    name: Build Docusaurus
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js 15
-        uses: actions/setup-node@v1
+      - uses: actions/checkout@v4
         with:
-          node-version: '15'
-      - run: npm ci
-      - run: npm run build
-      - name: setup git config
-        run: |
-          git config user.name "GitHub Actions Bot"
-          git config user.email "<>"
-      - name: Deploy assembled spec
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm install --frozen-lockfile
+
+      - name: Build specs and website
         run: |
-          git checkout -b assembled-spec
-          git add -f openrpc.json
-          git add -f refs-openrpc.json
-          git commit -m "assemble openrpc.json"
-          git push -fu origin assembled-spec
-  deploy-gh-pages:
+          npm run build
+          npm run build:docs
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Use Node.js 15
-        uses: actions/setup-node@v1
-        with:
-          node-version: '15'
-      - run: npm ci
-      - run: npm run build
-      - run: npm run generate-clients
-      - run: 'sed -i -e "s|Prefix: \"\"|Prefix: \"/execution-apis\"|g" build/docs/gatsby/gatsby-config.js'
-      - run: 'sed -i -e "s|/api|api|g" build/docs/gatsby/src/pages/index.tsx'
-      - run: npm run build:docs
-      - name: setup git config
-        run: |
-          git config user.name "GitHub Actions Bot"
-          git config user.email "<>"
       - name: Deploy to GitHub Pages
-        if: success()
-        uses: crazy-max/ghaction-github-pages@v3
-        with:
-          target_branch: gh-pages
-          build_dir: build/docs/gatsby/public
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/deploy.yaml.old

@@ -0,0 +1,59 @@
+name: Deploy specification
+
+on:
+  push:
+    branches:
+      - main
+
+env:
+  # this avoids node running out of memory while building
+  NODE_OPTIONS: --max_old_space_size=20480
+
+jobs:
+  deploy-spec:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 15
+        uses: actions/setup-node@v1
+        with:
+          node-version: '15'
+      - run: npm ci
+      - run: npm run build
+      - name: setup git config
+        run: |
+          git config user.name "GitHub Actions Bot"
+          git config user.email "<>"
+      - name: Deploy assembled spec
+        run: |
+          git checkout -b assembled-spec
+          git add -f openrpc.json
+          git add -f refs-openrpc.json
+          git commit -m "assemble openrpc.json"
+          git push -fu origin assembled-spec
+  deploy-gh-pages:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Use Node.js 15
+        uses: actions/setup-node@v1
+        with:
+          node-version: '15'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run generate-clients
+      - run: 'sed -i -e "s|Prefix: \"\"|Prefix: \"/execution-apis\"|g" build/docs/gatsby/gatsby-config.js'
+      - run: 'sed -i -e "s|/api|api|g" build/docs/gatsby/src/pages/index.tsx'
+      - run: npm run build:docs
+      - name: setup git config
+        run: |
+          git config user.name "GitHub Actions Bot"
+          git config user.email "<>"
+      - name: Deploy to GitHub Pages
+        if: success()
+        uses: crazy-max/ghaction-github-pages@v3
+        with:
+          target_branch: gh-pages
+          build_dir: build/docs/gatsby/public
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-deploy.yaml

@@ -0,0 +1,29 @@
+name: Test deployment
+
+on:
+  pull_request:
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+  workflow_dispatch:
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm install --frozen-lockfile
+      - name: Test build website
+        run: |
+          npm run build
+          npm run build:docs

.gitignore

@@ -7,3 +7,4 @@ data.json
 schema.json
 *.dic
 .idea/
+.docusaurus

css/custom.css

@@ -0,0 +1,30 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}

docs/reference/intro.md

@@ -0,0 +1,43 @@
+---
+slug: /
+sidebar_position: 1
+---
+
+# Introduction
+
+Welcome to the Ethereum Execution APIs documentation. This documentation provides comprehensive information about the JSON-RPC APIs provided by Ethereum 1.0 clients.
+
+## What are Execution APIs?
+
+Execution APIs are the set of JSON-RPC endpoints that allow applications to interact with Ethereum nodes. These APIs enable developers to:
+
+- Query blockchain data
+- Send transactions
+- Interact with smart contracts
+- Monitor network status
+- And much more
+
+## Getting Started
+
+To get started with the Execution APIs:
+
+1. Choose an Ethereum client implementation
+2. Set up your development environment
+3. Connect to an Ethereum node
+4. Start making JSON-RPC calls
+
+## API Categories
+
+The Execution APIs are organized into several categories:
+
+- Core APIs
+- Account APIs
+- Network APIs
+- Debug APIs
+- Trace APIs
+
+Each category serves specific purposes and provides different functionalities for interacting with the Ethereum network.
+
+## Contributing
+
+We welcome contributions to improve this documentation. Please see our [Making Changes](/reference/making-changes) guide for more information on how to contribute. 

docs/making-changes.md → docs/reference/making-changes.md

@@ -115,4 +115,4 @@ others don't.
 
 [exec-apis]: https://github.com/ethereum/execution-apis
 [pm]: https://github.com/ethereum/pm
-[test-gen]: ../tests/README.md
+[test-gen]: https://github.com/ethereum/execution-apis/blob/main/tests/README.md

docusaurus.config.ts

@@ -0,0 +1,103 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@metamask/docusaurus-openrpc/dist/preset';
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+const config: Config = {
+  title: 'Ethereum Execution APIs',
+  tagline: 'A JSON-RPC specification for Ethereum execution clients',
+  favicon: 'img/favicon.ico',
+
+  // Set the production url of your site here
+  url: 'https://ethereum.github.io',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/execution-apis/',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'ethereum', // Usually your GitHub org/user name.
+  projectName: 'execution-apis', // Usually your repo name.
+  deploymentBranch: 'gh-pages',
+
+  onBrokenLinks: 'warn',
+  onBrokenMarkdownLinks: 'warn',
+
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      '@metamask/docusaurus-openrpc/dist/preset',
+      /** @type {import('@metamask/docusaurus-openrpc/dist/preset').Options} */
+      {
+        docs: {
+          routeBasePath: '/',
+          openrpc: {
+            openrpcDocument: './refs-openrpc.json',
+            path: 'reference',
+            sidebarLabel: 'JSON-RPC',
+          },
+          sidebarPath: './sidebars.ts',
+          path: './docs',
+        },
+        blog: false,
+        theme: {
+          customCss: './css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    // Replace with your project's social card
+    image: 'img/docusaurus-social-card.jpg',
+    navbar: {
+      title: 'Execution APIs',
+      // logo: {
+      //   alt: 'My Site Logo',
+      //   src: 'img/logo.svg',
+      // },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'referenceSidebar',
+          position: 'left',
+          label: 'API Reference',
+        },
+        {
+          href: 'https://github.com/ethereum/execution-apis',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'GitHub',
+              href: 'https://github.com/ethereum/execution-apis',
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} Ethereum. Built with Docusaurus.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;