mcaxl/docs/astro.config.mjs

// @ts-check
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import icon from 'astro-icon';
import mermaid from 'astro-mermaid';
import starlightPageActions from 'starlight-page-actions';

// Reverse-proxy / HMR awareness. `DOMAIN` is injected by docker-compose
// (DEV_DOMAIN for the dev service, DOMAIN for prod). When unset, we
// assume plain local dev on http://localhost:4321.
const DOMAIN = process.env.DOMAIN || 'localhost';
const IS_BEHIND_PROXY = DOMAIN !== 'localhost';

export default defineConfig({
  // Disabled per workspace convention.
  telemetry: false,
  devToolbar: { enabled: false },

  site: IS_BEHIND_PROXY ? `https://${DOMAIN}` : undefined,

  // Shiki doesn't ship a Cisco IOS grammar. Map `cisco` → `ini` (closest
  // visual match — `!` line comments, "keyword value" shape). Silences
  // build-time warnings for any Cisco code fences in narrative pages.
  // `env` (dotenv files) → `bash` so the KEY=value syntax highlights.
  markdown: {
    shikiConfig: {
      langAlias: {
        cisco: 'ini',
        env: 'bash',
      },
    },
  },

  integrations: [
    // Mermaid must come BEFORE starlight — its remark/rehype plugin has
    // to register before Starlight sets up its MDX pipeline. Renders
    // client-side (no build-time SVG generation).
    mermaid({
      theme: 'default',
      autoTheme: true, // follows light/dark mode toggle
    }),
    icon({
      include: {
        lucide: ['*'],
      },
    }),
    starlight({
      title: 'mcaxl docs',
      description:
        'Read-only MCP server for Cisco Unified Communications Manager (CUCM) — AXL SOAP API + RisPort70 audit. Documentation.',
      logo: {
        src: './src/assets/logo.svg',
        replacesTitle: false,
      },
      customCss: ['./src/styles/custom.css'],

      // Per-page action buttons: "Copy Markdown" + "View in Markdown"
      // (.md route) + "Share" menus. Open-in-AI actions disabled because
      // they assume the third-party AI can fetch the URL — fine here for
      // a public site, but kept off to match the operator preference for
      // copy-and-paste handoffs.
      plugins: [
        starlightPageActions({
          actions: {
            chatgpt: false,
            claude: false,
          },
        }),
      ],

      lastUpdated: true,
      pagination: true,
      social: [
        {
          icon: 'external',
          label: 'PyPI',
          href: 'https://pypi.org/project/mcaxl/',
        },
        {
          icon: 'external',
          label: 'Gitea repo',
          href: 'https://git.supported.systems/mcp/mcaxl',
        },
      ],
      editLink: {
        baseUrl: 'https://git.supported.systems/mcp/mcaxl/_edit/main/docs/',
      },
      sidebar: [
        {
          label: 'Overview',
          items: [
            { label: 'Home', link: '/' },
          ],
        },
        {
          label: 'Getting started',
          collapsed: false,
          autogenerate: { directory: 'getting-started' },
        },
        {
          label: 'How-to guides',
          collapsed: false,
          autogenerate: { directory: 'how-to' },
        },
        {
          label: 'Reference',
          collapsed: false,
          autogenerate: { directory: 'reference' },
        },
        {
          label: 'Explanation',
          collapsed: true,
          autogenerate: { directory: 'explanation' },
        },
      ],
    }),
  ],

  vite: {
    server: {
      host: '0.0.0.0',
      // HMR survives behind a Caddy-terminated TLS reverse proxy when
      // configured this way. Leaves localhost dev untouched.
      hmr: IS_BEHIND_PROXY
        ? {
            host: DOMAIN,
            protocol: 'wss',
            clientPort: 443,
          }
        : undefined,
    },
  },
});