feat(mkdocs): move to mkdocs-material

.github/workflows/check-links.yml

@@ -11,11 +11,11 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: gaurav-nelson/github-action-markdown-link-check@v1
-        # checks all markdown files from /book including all subfolders
+        # checks all markdown files from /docs including all subfolders
         with:
           use-quiet-mode: 'yes'
           use-verbose-mode: 'yes'
-          folder-path: 'book/'
+          folder-path: 'docs/'
       - uses: actions/checkout@v4
       - uses: gaurav-nelson/github-action-markdown-link-check@v1
         # checks all markdown files from root but ignores subfolders

.github/workflows/deploy.yaml

@@ -1,63 +1,25 @@
-name: Deploy VitePress site to Pages
-
+name: Deploy website
 on:
-  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
-  # using the `master` branch as the default branch.
   push:
-    branches: [master]
-
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    branches:
+      - master 
+      - main
 permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
+  contents: write
 jobs:
-  # Build job
-  build:
-    runs-on: ubuntu-22.04
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 0 # Not needed if lastUpdated is not enabled
-      # - uses: pnpm/action-setup@v2 # Uncomment this if you're using pnpm
-      - name: Setup Node
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          cache: npm # or pnpm / yarn
-      - name: Setup Pages
-        uses: actions/configure-pages@v3
-      - name: Install dependencies
-        run: npm ci
-      - name: Build with VitePress
-        run: |
-          npm run docs:build
-          touch .vitepress/dist/.nojekyll
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v2
-        with:
-          path: .vitepress/dist
-
-  # Deployment job
   deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    needs: build
     runs-on: ubuntu-latest
-    name: Deploy
     steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -7,3 +7,4 @@ tests/Cargo.lock
 tests/target
 tests/src
 tests/config.txt
+site

README.md

@@ -1,10 +1,42 @@
-# Readme
+# Book of BDK
+
+This repository hosts the code and content for the [Book of BDK website](https://thunderbiscuit.github.io/book-of-bdk/).
+We use [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material) to render the website and the content.
 
 ## Develop locally
+
+To develop locally, you'll need to install `mkdocs-material`:
+
+```shell
+pip install mkdocs-material
+```
+
+You can serve the site with [`just`](https://just.systems/man/en/):
+
 ```shell
-# on first build
-npm install
+just serve
+```
+
+All the rust code can be tested with:
+
+```
+just test
+```
+
+NOTE: Some tests need additional dependencies on macOS such as `libiconv`.
+
+A [Nix](https://nixos.org) shell can be instantiated with:
 
-# run the dev site
-npm run docs:dev
+```nix
+with import <nixpkgs> { };
+mkShell {
+  nativeBuildInputs = [
+    bashInteractive
+    python311Packages.mkdocs-material
+    # macOS specifics
+    libiconv
+    darwin.apple_sdk.frameworks.Security
+    darwin.apple_sdk.frameworks.SystemConfiguration
+  ];
+}
 ```