site: add interactive formal spec (#349)

* site: agda web
* scripts: add transform script
* fix: css restore; add search
* fix: offset and link selection
* site: add static formal spec
* git: add workflow for updating formal spec

Author: will-break-it

.github/workflows/formal-spec-integration.yaml

@@ -0,0 +1,59 @@
+name: "formal-spec-integration"
+
+on:
+  workflow_run:
+    workflows: ["formal-spec"]
+    types:
+      - completed
+    branches:
+      - main
+
+jobs:
+  integrate-formal-spec:
+    name: "Integrate Formal Spec"
+    runs-on: ubuntu-22.04
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: 📥 Checkout Leios site
+        uses: actions/checkout@v4
+        with:
+          repository: input-output-hk/ouroboros-leios
+          token: ${{ secrets.GH_PAT }}
+
+      - name: 📥 Download formal spec HTML
+        uses: dawidd6/action-download-artifact@v2
+        with:
+          workflow: formal-spec.yaml
+          name: formal-spec-html
+          repo: input-output-hk/ouroboros-leios-formal-spec
+          token: ${{ secrets.GH_PAT }}
+
+      - name: 🏗️ Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: "yarn"
+          cache-dependency-path: ./site/yarn.lock
+
+      - name: 📦 Install dependencies
+        working-directory: site
+        run: yarn install
+
+      - name: 📝 Update formal spec
+        run: |
+          # Create formal spec directory if it doesn't exist
+          mkdir -p site/static/formal-spec
+          # Copy the HTML files
+          cp -r formal-spec-html/* site/static/formal-spec/
+
+      - name: 🏗️ Build Docusaurus site
+        working-directory: site
+        run: |
+          yarn build
+
+      - name: 🚀 Publish GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site/build
+          cname: leios.cardano-scaling.org 

site/docusaurus.config.ts

@@ -1,6 +1,7 @@
 import type * as Preset from "@docusaurus/preset-classic";
 import type { Config } from "@docusaurus/types";
 import { themes as prismThemes } from "prism-react-renderer";
+import path from 'path';
 
 const config: Config = {
     title: "Ouroboros Leios",
@@ -37,6 +38,13 @@ const config: Config = {
         },
     ],
 
+    // Configure static file serving
+    staticDirectories: ['static', 'public'],
+
+    // Configure plugins
+    plugins: [
+    ],
+
     presets: [
         [
             "classic",
@@ -87,6 +95,11 @@ const config: Config = {
                     position: "left",
                     label: "Development",
                 },
+                {
+                    to: "/formal-spec/",
+                    label: "Formal Specification",
+                    position: "left",
+                },
                 { to: "/news", label: "Weekly updates", position: "right" },
                 {
                     type: "dropdown",
@@ -142,6 +155,10 @@ const config: Config = {
                             label: "How it works",
                             to: "/docs/how-it-works",
                         },
+                        {
+                            label: "Formal Specification",
+                            to: "/formal-spec/",
+                        },
                         {
                             label: "FAQs",
                             to: "/docs/faq",

site/scripts/build-agda-docs.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# Exit on error
+set -e
+
+# Get the directory of this script
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SITE_DIR="$(dirname "$SCRIPT_DIR")"
+FORMAL_SPEC_DIR="$(cd "$SITE_DIR/../../../ouroboros-leios-formal-spec" && pwd)"
+
+echo "Building Agda documentation..."
+cd "$FORMAL_SPEC_DIR"
+nix build .#leiosDocs
+
+echo "Copying Agda HTML files..."
+mkdir -p "$SITE_DIR/static/agda_html"
+cp -r result/share/doc/agda/html/* "$SITE_DIR/static/agda_html/"
+
+echo "Processing Agda HTML files..."
+cd "$SITE_DIR"
+node scripts/process-agda-html.js
+
+echo "Done! The Agda specification is now available at /agda_html/" 

site/scripts/dev-with-formal-spec.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+# Exit on error
+set -e
+
+# Get the directory of this script
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SITE_DIR="$(dirname "$SCRIPT_DIR")"
+FORMAL_SPEC_DIR="$(cd "$SITE_DIR/../../ouroboros-leios-formal-spec" && pwd)"
+
+echo "Building Agda documentation..."
+cd "$FORMAL_SPEC_DIR"
+
+# Add Nix configuration for trusted users
+export NIX_CONFIG="trusted-users = root $USER
+substituters = https://cache.nixos.org/
+trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY="
+
+# Build the docs with --impure to handle dirty git tree
+nix build .#leiosDocs --impure
+
+echo "Copying Agda HTML files..."
+mkdir -p "$SITE_DIR/static/agda_html"
+
+# Backup our custom CSS if it exists
+if [ -f "$SITE_DIR/static/agda_html/agda.css" ]; then
+    cp "$SITE_DIR/static/agda_html/agda.css" "$SITE_DIR/static/agda_html/agda.css.bak"
+fi
+
+# Copy all files except Agda.css
+cp -r result/share/doc/agda/html/* "$SITE_DIR/static/agda_html/"
+
+# Restore our custom CSS
+if [ -f "$SITE_DIR/static/agda_html/agda.css.bak" ]; then
+    mv "$SITE_DIR/static/agda_html/agda.css.bak" "$SITE_DIR/static/agda_html/agda.css"
+fi
+
+echo "Processing Agda HTML files..."
+cd "$SITE_DIR"
+node scripts/process-agda-html.js
+
+echo "Starting development server..."
+yarn start