astro.config.mjs

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import starlightLinksValidator from "starlight-links-validator";
import starlightLlmsTxt from "starlight-llms-txt";
import starlightPageActions from "starlight-page-actions";
import rehypeMermaid from "rehype-mermaid";

// https://astro.build/config
export default defineConfig({
  site: "https://theagenticguy.github.io",
  base: "/opencodehub",
  // Mermaid: render ```mermaid ``` fences to inline SVG at build time.
  // excludeLangs is critical — without it, Shiki grabs the mermaid fence
  // first and rehype-mermaid never sees it.
  markdown: {
    syntaxHighlight: { type: "shiki", excludeLangs: ["mermaid"] },
    rehypePlugins: [[rehypeMermaid, { strategy: "img-svg", dark: true }]],
  },
  integrations: [
    starlight({
      title: "OpenCodeHub",
      description:
        "Apache-2.0 code intelligence graph + MCP server for AI coding agents. 29 tools, 15 GA languages, single-file SQLite storage, WASM-only parsing, deterministic, offline-capable.",
      logo: {
        src: "./src/assets/logo.svg",
        replacesTitle: false,
      },
      favicon: "/favicon.svg",
      social: [
        {
          icon: "github",
          label: "GitHub",
          href: "https://github.com/theagenticguy/opencodehub",
        },
      ],
      editLink: {
        baseUrl:
          "https://github.com/theagenticguy/opencodehub/edit/main/packages/docs/",
      },
      lastUpdated: true,
      credits: true,
      plugins: [
        // 1) LLM-crawlable bundles. Emits /llms.txt, /llms-full.txt,
        //    /llms-small.txt at build time. Must run first so page-actions
        //    sees it already registered.
        starlightLlmsTxt({
          projectName: "OpenCodeHub",
          description:
            "Apache-2.0 code intelligence graph + MCP server for AI coding agents. Gives agents callers, callees, processes, and blast radius in one MCP tool call — local, offline-capable, deterministic.",
          details:
            "OpenCodeHub indexes a repository into a hybrid structural + semantic knowledge graph and exposes it over the Model Context Protocol (MCP) to AI coding agents. The MCP server registers 29 tools across five families — exploration (list_repos, query, context, impact, detect_changes, sql, signature), group / federation (group_list, group_query, group_status, group_contracts, group_cross_repo_links, group_sync), scan / findings / verdict (scan, list_findings, list_findings_delta, list_dead_code, license_audit, verdict, change_pack, risk_trends), HTTP / routing (route_map, api_impact, shape_check, tool_map), and meta (project_profile, dependencies, owners, pack_codebase). The CLI binary is `codehub`. Runtime: Node 24.15+, pnpm 11, a single-file SQLite store (`<repo>/.codehub/store.sqlite`, via Node's built-in node:sqlite) that backs graph nodes, edges, embeddings, and the temporal tables — zero native storage bindings (ADR 0019), web-tree-sitter (WASM) is the only parse runtime with all 15 grammar `.wasm` blobs vendored at packages/ingestion/vendor/wasms/, 15 GA languages, SCIP indexers for TypeScript / TSX / JavaScript / Python / Go / Rust / Java / C# / C / C++ / Kotlin / Ruby. 19-scanner inventory. Apache-2.0 end to end. Repos are first-class graph nodes (`repo_uri`); the cross-repo `group_*` family fans out over named groups; AMBIGUOUS_REPO error envelope returns `choices[]` so a caller can retry deterministically.",
          promote: [
            "start-here/**",
            "agents/**",
            "guides/**",
            "mcp/**",
          ],
          demote: [
            "architecture/**",
            "contributing/**",
          ],
          // Keep llms-small.txt tight by dropping internals-y prose.
          exclude: [],
          minify: {
            note: true,
            tip: true,
            details: true,
            whitespace: true,
            caution: false,
            danger: false,
          },
          customSets: [
            {
              label: "user-guide",
              paths: ["start-here/**", "guides/**"],
              description:
                "User-facing pages only: install, quick-start, editor integration guides, group and indexing guides.",
            },
            {
              label: "agents",
              paths: ["agents/**", "mcp/**"],
              description:
                "Agent-side reference: per-editor MCP setup, the 29-tool catalog, tool decision matrix, idiomatic prompts.",
            },
            {
              label: "mcp",
              paths: ["mcp/**", "reference/**"],
              description:
                "MCP surface: server tools, resources, CLI reference, error codes, language matrix, .docmeta.json schema.",
            },
            {
              label: "contributing",
              paths: ["contributing/**", "architecture/**"],
              description:
                "Developer and architecture docs: dev loop, release flow, ADRs, determinism, supply-chain, storage backend, cross-repo federation.",
            },
          ],
        }),

        // 2) Per-page "Copy as Markdown" + "Open in ChatGPT" + "Open in
        //    Claude" + Share. IMPORTANT: do NOT set `baseUrl`, or this
        //    plugin will try to own /llms.txt too and collide with
        //    starlight-llms-txt. Leave llms generation to plugin #1.
        starlightPageActions({
          actions: {
            markdown: true,
            chatgpt: true,
            claude: true,
            t3chat: false,
            v0: false,
          },
          share: true,
        }),

        // 3) Build-time broken-link check. Runs after content is built
        //    but before deploy, so llms-full.txt never ships dead links.
        starlightLinksValidator({
          errorOnFallbackPages: false,
          errorOnInconsistentLocale: false,
        }),
      ],
      sidebar: [
        {
          label: "Start here",
          items: [{ autogenerate: { directory: "start-here" } }],
        },
        {
          label: "Agents",
          items: [{ autogenerate: { directory: "agents" } }],
        },
        {
          label: "MCP",
          items: [{ autogenerate: { directory: "mcp" } }],
        },
        {
          label: "Reference",
          items: [{ autogenerate: { directory: "reference" } }],
        },
        {
          label: "Guides",
          items: [{ autogenerate: { directory: "guides" } }],
        },
        {
          label: "Architecture",
          items: [{ autogenerate: { directory: "architecture" } }],
        },
        {
          label: "Skills",
          items: [{ autogenerate: { directory: "skills" } }],
        },
        {
          label: "Contributing",
          items: [{ autogenerate: { directory: "contributing" } }],
        },
      ],
      customCss: ["./src/styles/custom.css"],
    }),
  ],
});