ci: add workflows for publishing to GH Pages (#13)

- Deploy every commit on `main` with relevant changes.
- Generate and publish previews for every PR with relevant changes.

.github/actions/build-mdbook/action.yaml

@@ -0,0 +1,28 @@
+name: Build the mdBook
+description: Generate static site from markdown files through mdBook
+
+runs:
+  using: "composite"
+  steps:
+    - name: Create bin directory and add to $PATH
+      run: |
+        mkdir bin
+        echo "$(pwd)/bin" >> ${GITHUB_PATH}
+      shell: bash
+    - name: Install mdbook
+      run: |
+        url="https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz"
+        curl -sSL "$url" | tar -xz --directory=bin
+      shell: bash
+    - name: Install mdbook-linkcheck
+      run: |
+        url="https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip"
+        curl -sSL "$url" -o mdbook-linkcheck.zip
+        unzip "$_" -d bin
+        chmod +x bin/mdbook-linkcheck
+      shell: bash
+    - name: Build the book and check for broken links
+      run: mdbook build
+      env:
+        RUST_LOG: INFO
+      shell: bash

.github/workflows/pages-deploy.yaml

@@ -0,0 +1,28 @@
+name: Build and deploy GitHub Pages
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - "book.toml"
+      - "docs/**"
+      - ".github/actions/build-mdbook/action.yaml"
+      - ".github/workflows/pages-deploy.yaml"
+
+concurrency: ci-${{ github.ref }}
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/build-mdbook
+      - name: Deploy
+        uses: JamesIves/[email protected]
+        with:
+          folder: build/html
+          clean-exclude: pr-preview/
+          force: false

.github/workflows/pages-preview.yaml

@@ -0,0 +1,33 @@
+name: Build and deploy GitHub Pages preview for PRs
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+    paths:
+      - "book.toml"
+      - "docs/**"
+      - ".github/actions/build-mdbook/action.yaml"
+      - ".github/workflows/pages-preview.yaml"
+
+
+concurrency: preview-${{ github.ref }}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/build-mdbook
+        if: github.event.action != 'closed'
+      - name: Deploy preview
+        uses: rossjrw/[email protected]
+        with:
+          source-dir: build/html

book.toml

@@ -7,3 +7,13 @@ title = "Walrus"
 
 [build]
 build-dir = "build"
+
+[output.html]
+
+[output.linkcheck]
+optional = true
+follow-web-links = true
+warning-policy = "error"
+exclude = [
+  'github\.com/MystenLabs/walrus-docs/', # Currently still private
+]