Artifact [0fb9f191cc]

Artifact 0fb9f191ccc1ba6460c5d447f4f3f01edde396e7ddf2178f582f47cf62373b05:

• Executable file scripts/prepend-sdk-frontmatter.sh — part of check-in [f30849a466] at 2026-04-26 14:14:53 on branch trunk — docs: usability improvements from DX audit (#9)

  Implements all seven recommended changes from the docs audit:

  1. SDK pages now show package names in nav. Add scripts/prepend-sdk-frontmatter.sh that prepends '--- title: <pkg> ---' to each gomarkdoc-generated api.md; wired into 'make docs-gen-sdk'. Sidebar previously showed five undifferentiated 'API' entries; now shows cli, db, dst, libfossil, observer/otel.

  2. /examples/ populated with paragraphs + GitHub deep-links for embed-repo-api and wasm. No longer a placeholder pointing back at the repo.

  3. Architecture page gets an inline SVG mirroring the landing-page diagram. Self-contained CSS (uses currentColor + ember accent) so it tracks Hextra's light/dark theme without depending on the landing's CSS scope.

  4. Cross-links added: quickstart -> production + extension-points, migration -> architecture, architecture -> extension-points. Extension Points and Production patterns are now reachable via prose, not just the sidebar.

  5. /docs/ landing expanded from 3 sentences to a 7-line subsection map calling out each page's purpose.

  6. Version indicator in navbar (libfossil v0.4.2). Override layouts/_partials/navbar-title.html mimics Hextra's default and appends a small mono version tag from .Site.Params.version.

  7. New /docs/production/ page covering error handling, context cancellation, telemetry wiring, repo-handle lifetime, and driver selection — the patterns the quickstart's log.Fatal shortcuts gloss over. (user: [email protected], size: 861) [annotate] [blame] [check-ins using]

#!/usr/bin/env bash
# Prepend Hugo frontmatter to gomarkdoc-generated SDK pages so each page's
# nav label is the package name instead of the filename ("api"). Idempotent:
# strips any existing frontmatter and re-injects, so re-running after
# `make docs-gen-sdk` produces stable bytes.
set -euo pipefail

SDK_ROOT="docs/site/content/docs/reference/sdk"

while IFS= read -r f; do
    rel="${f#${SDK_ROOT}/}"
    pkg="${rel%/api.md}"

    if head -1 "$f" | grep -qE '^---$'; then
        awk 'NR==1 && /^---$/ { in_fm=1; next }
             in_fm && /^---$/ { in_fm=0; next }
             !in_fm' "$f" > "$f.body"
    else
        cp "$f" "$f.body"
    fi

    {
        printf -- '---\n'
        printf 'title: %s\n' "$pkg"
        printf -- '---\n\n'
        cat "$f.body"
    } > "$f"
    rm "$f.body"
done < <(find "$SDK_ROOT" -name 'api.md' -type f | sort)