docs.yml

name: docs
on:
  # Manual runs materialize a reviewed non-Pages branch in place. The release
  # gate verifies the exact source SHA and the generated child commit before
  # either commit can be promoted to master.
  workflow_dispatch:

  # Pushes to master that touch docs or wasm/docs
  push:
    branches:
      - master
    paths:
      - 'docs/**'
      - 'wasm/**'
      - '.github/workflows/docs.yml'

permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Validate materialization ref
        shell: bash
        run: |
          set -euo pipefail
          test "$(git rev-parse HEAD)" = "${GITHUB_SHA}"
          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
            test "${GITHUB_REF_TYPE}" = "branch"
            test "${GITHUB_REF_NAME}" != "master"
            test "${GITHUB_REF_NAME}" != "gh-pages"
          else
            test "${GITHUB_EVENT_NAME}" = "push"
            test "${GITHUB_REF}" = "refs/heads/master"
          fi

      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com

      # Setup Node.js for wasm-daflatbuffers demo build
      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: 'npm'
          cache-dependency-path: wasm/docs/package-lock.json

      # Install parent wasm package dependencies (needed for ../src imports)
      - name: Install wasm package dependencies
        working-directory: wasm
        run: npm ci

      # Build wasm-daflatbuffers demo (this will be the landing page)
      - name: Build wasm-daflatbuffers demo
        working-directory: wasm/docs
        run: |
          echo "=== Checking required files ==="
          ls -la ../src/
          ls -la ../dist/
          echo "=== Installing dependencies ==="
          npm ci
          echo "=== Building demo ==="
          npm run build

      - name: Record reviewed source and landing digest
        shell: bash
        run: |
          set -euo pipefail
          source_commit="$(git rev-parse HEAD)"
          dist_tree_sha256="$(
            node --input-type=module <<'NODE'
          import { createHash } from "node:crypto";
          import { readdirSync, readFileSync } from "node:fs";
          import { posix, resolve } from "node:path";

          const root = resolve("wasm/docs/dist");
          const files = [];
          function walk(directory, prefix = "") {
            for (const entry of readdirSync(directory, { withFileTypes: true })) {
              const relative = prefix ? posix.join(prefix, entry.name) : entry.name;
              const path = resolve(directory, entry.name);
              if (entry.isDirectory()) walk(path, relative);
              else if (entry.isFile()) files.push([relative, path]);
              else throw new Error(`unsupported dist entry: ${relative}`);
            }
          }
          walk(root);
          files.sort(([left], [right]) => left.localeCompare(right, "en"));
          const tree = createHash("sha256");
          for (const [relative, path] of files) {
            const fileDigest = createHash("sha256").update(readFileSync(path)).digest("hex");
            tree.update(`${fileDigest}  ${relative}\n`, "utf8");
          }
          process.stdout.write(tree.digest("hex"));
          NODE
          )"
          {
            echo "### FlatBuffers docs materialization"
            echo "- Source commit: \`${source_commit}\`"
            echo "- dist tree SHA-256: \`${dist_tree_sha256}\`"
          } >> "${GITHUB_STEP_SUMMARY}"

      # Setup Python for mkdocs
      - uses: actions/setup-python@v6
        with:
          python-version: 3.x

      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV

      - uses: actions/cache@v5
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-

      - run: pip install mkdocs-material mkdocs-redirects

      # Build mkdocs documentation
      - name: Build mkdocs site
        run: mkdocs build -f mkdocs.yml -d ../mkdocs-site
        working-directory: docs

      # Assemble final site into /docs folder (served from master branch)
      - name: Assemble site
        shell: bash
        run: |
          set -euo pipefail
          # Replace the complete landing tree while preserving only the
          # explicitly reviewed documentation inputs and generated doc sets.
          node wasm/docs/scripts/materialize-pages.mjs \
            --source wasm/docs/dist \
            --destination docs

          # Copy mkdocs documentation to /docs/site subdirectory
          mkdir -p docs/site
          cp -r mkdocs-site/* docs/site/

          # Convert WASM runtime markdown docs to styled HTML
          if [ -d "wasm/docs/docs" ]; then
            mkdir -p docs/docs-html docs/wasm-runtimes
            cd wasm/docs && node scripts/build-markdown.mjs && cd ../..
            cp -r wasm/docs/docs-html/* docs/docs-html/
            cp -r wasm/docs/docs-html/* docs/wasm-runtimes/
          fi

          node wasm/docs/scripts/materialize-pages.mjs \
            --source wasm/docs/dist \
            --destination docs \
            --check

      - name: Commit generated docs to the source branch
        shell: bash
        run: |
          set -euo pipefail
          git add docs/
          git diff --staged --quiet && echo "No changes to commit" && exit 0
          git commit -m "Update docs site from ${GITHUB_SHA} [skip ci]"
          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
            test "${GITHUB_REF_NAME}" != "master"
            test "${GITHUB_REF_NAME}" != "gh-pages"
            git push origin "HEAD:${GITHUB_REF}"
          else
            test "${GITHUB_REF}" = "refs/heads/master"
            git push origin "HEAD:refs/heads/master"
          fi