docs: publish to GitHub pages

.github/workflows/docs-publish.yml

@@ -0,0 +1,71 @@
+name: Publish docs to GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+      - .github/workflows/docs_publish.yml
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - docs/**
+      - .github/workflows/docs_publish.yml
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  preview:
+    name: Preview docs
+    runs-on: ubuntu-24.04
+    if: (github.repository_owner == github.event.pull_request.head.repo.owner.login) && (github.event_name == 'pull_request')
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set base URL
+        run: |
+          sed -i "s|baseUrl: '/constellation/'|baseUrl: '/constellation/pr-preview/pr-${{ github.event.number }}/'|" ./docs/docusaurus.config.js
+
+      - name: Build
+        working-directory: ./docs
+        run: |
+          npm i && npm run build
+
+      - name: Deploy Preview
+        uses: rossjrw/pr-preview-action@8ff09e486b4c23709012eedd3b42e9f0b95dd0c5 # v1.6.3
+        with:
+          source-dir: ./docs/build
+
+  publish:
+    name: Publish docs to GitHub Pages
+    runs-on: ubuntu-24.04
+    if: github.event_name == 'push' && github.ref_name == 'main'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
+        with:
+          persist-credentials: false
+
+      - name: Build
+        working-directory: ./docs
+        run: |
+          npm i && npm run build
+
+      - name: Publish
+        uses: JamesIves/github-pages-deploy-action@4a3abc783e1a24aeb44c16e869ad83caf6b4cc23 # v4.7.4
+        with:
+          folder: ./docs/build
+          branch: gh-pages
+          clean-exclude: pr-preview
+          force: false

docs/docusaurus.config.js

@@ -12,7 +12,6 @@ async function createConfig() {
     url: 'https://docs.edgeless.systems',
     baseUrl: '/constellation/',
     onBrokenLinks: 'throw',
-    onBrokenMarkdownLinks: 'throw',
     onBrokenAnchors: 'throw',
     favicon: 'img/favicon.ico',
 
@@ -41,6 +40,9 @@ async function createConfig() {
     // mermaid
     markdown: {
       mermaid: true,
+      hooks: {
+        onBrokenMarkdownLinks: 'throw',
+      },
     },
     themes: ['@docusaurus/theme-mermaid'],