docs(guide): simplify url routes

Modifies the firebase hosting config to remove the `/<version>/`
prefix from the guide URLs, which has only ever been `/main/`, due to #6.
Also includes rewrites so that historical URLs with the `/main/` prefix
will still be honored, and redirected to the appropriate location that's
live in the docs.

Squirreling away this one-liner for generating a "sitemap" of all URLs:

    curl -s http://localhost:5000 \
        | rg -i 'class="chapter"' \
        | perl -npE 's/href=/\nhref=/g ' \
        | perl -nE  '/href="([\w.\/]+)"/g and say $1' > sitemap.txt

which was helpful in creating the redirects.

Removes the mdboook-only meta-refresh redirects added in #4232,
because the browser UX was atrocious. Refs #3417.

.github/workflows/notes.yml

@@ -36,23 +36,15 @@ jobs:
         run: cargo +nightly install mdbook mdbook-katex mdbook-mermaid mdbook-linkcheck
 
       - name: Build software guide
-        run: cd docs/guide && mdbook build
-
-      - name: Move software guide to subdirectory
-        run: |
-          cd docs/guide
-          rm -rf firebase-tmp
-          mkdir firebase-tmp
-          mv book/html firebase-tmp/${{ github.event.inputs.image_tag || github.ref_name }}
-          tree firebase-tmp
+        working-directory: docs/guide
+        run: mdbook build
 
       - name: Deploy software guide to firebase
         uses: w9jds/[email protected]
         with:
           args: deploy
         env:
           FIREBASE_TOKEN: ${{ secrets.FIREBASE_TOKEN }}
-          PROJECT_ID: penumbra-guide
           PROJECT_PATH: docs/guide
 
       - name: Build protocol spec

.gitignore

@@ -5,12 +5,12 @@ wallet-next/pwalletd-db.sqlite-wal
 
 *.DS_STORE
 
-book
+# mdbook docs builds
+docs/*/book/*
+# firebase config
 .firebase/
-# For some reason mdbook dumps this here because the main page is ../README.md
-#index.html
-# Used for deployments
-firebase-tmp/
+firebase-debug.log
+docs/*/firebase-tmp/
 
 # Nix build output goes here
 result

docs/guide/.firebaserc

@@ -0,0 +1,5 @@
+{
+  "projects": {
+    "default": "penumbra-guide"
+  }
+}

docs/guide/book.toml

@@ -27,17 +27,3 @@ warning-policy = "error"
 # The buf.build website doesn't support HTTP HEAD calls, returning 405.
 # Only relevant when `follow-web-links=true`.
 exclude = ['buf\.build']
-
-[output.html.redirect]
-# Renames in GH4215.
-"pd.html" = "node/pd.html"
-"pd/chain-upgrade.html" = "node/pd/chain-upgrade.html"
-"pd/debugging.html" = "node/pd/debugging.html"
-"pd/install.html" = "node/pd/install.html"
-"pd/join-testnet.html" = "node/pd/join-testnet.html"
-"pd/requirements.html" = "node/pd/requirements.html"
-"pd/validator.html" = "node/pd/validator.html"
-"pclientd.html" = "node/pclientd.html"
-"pclientd/build_transaction.html" = "node/pclientd/build_transaction.html"
-"pclientd/configure.html" = "node/pclientd/configure.html"
-"pclientd/rpc.html" = "node/pclientd/rpc.html"

docs/guide/firebase.json

@@ -1,16 +1,26 @@
 {
   "hosting": {
-    "public": "firebase-tmp",
-    "ignore": [
-      "firebase.json",
-      "**/.*",
-      "**/node_modules/**"
-    ],
+    "public": "book/html",
     "redirects": [
       {
-        "source": "/",
-        "destination": "/main/index.html",
-        "type": 301
+        "source": "/main/index.html",
+        "destination": "/",
+        "type": 302
+      },
+      {
+        "regex": "/main/pd(?P<page>.*)",
+        "destination": "/node/pd:page",
+        "type": 302
+      },
+      {
+        "regex": "/main/pclientd(?P<page>.*)",
+        "destination": "/node/pclientd:page",
+        "type": 302
+      },
+      {
+        "regex": "/main/(?P<page>.*)",
+        "destination": "/:page",
+        "type": 302
       }
     ]
   }

docs/guide/src/dev/docs.md

@@ -1,11 +1,17 @@
 # Building documentation
 
+## mdBook docs
 The [protocol docs] and the [guide] (this document) are built using
-[mdBook] and auto-deployed on pushes to `main`.  To build locally:
+[mdBook] and auto-deployed on pushes to `main`. To build locally:
 
-1. Install the requirements: `cargo install mdbook mdbook-katex mdbook-mermaid`
+1. Install the requirements: `cargo install mdbook mdbook-katex mdbook-mermaid mdbook-linkcheck`
 2. Run `mdbook serve` from `docs/protocol` (for the protocol spec) or from `docs/guide` (for this document).
 
+The hosting config uses [Firebase]. To debug Firebase-specific functionality like redirects,
+use `firebase emulators:start` to run a local webserver. You'll need to rebuild the docs
+with `mdbook build` to get livereload functionality, however.
+
+## Rust API docs
 The [Rust API docs][rustdoc] can be built with `./deployments/scripts/rust-docs`.
 The landing page, the top-level `index.html`, is handled as a special case.
 If you added new crates by appending a `-p <crate_name>` to the `rust-docs` script,
@@ -24,3 +30,4 @@ CI will automatically rebuild all our docs on merges into main.
 [rustdoc]: https://rustdoc.penumbra.zone
 [guide]: https://guide.penumbra.zone
 [mdBook]: https://rust-lang.github.io/mdBook/
+[Firebase]: https://firebase.google.com/docs/functions/local-emulator#install_the_firebase_cli