Ryan Malloy
f4c2a70bbf
Starlight, diataxis-shaped: a tutorial pair, six how-to guides, a generated tool reference plus a configuration reference, and four explanation pages covering architecture, sandbox isolation, see-and-drive, and the failure handling philosophy. The tool reference is generated from the running MCP server's own schemas, so its 33 tools, parameters and defaults cannot drift from the code; the generator asserts its grouping still covers exactly the live tool set. Infrastructure follows the warehacking cookie-cutter (multi-stage Dockerfile, Caddy serving dist with real 404 status, compose profiles for prod and dev, Makefile with a deploy target pointed at docker-2). Two deviations worth noting: remark-gfm is added to the MDX pipeline because Astro enables GFM for .md but not .mdx, so tables silently rendered as run-together paragraphs; and the card icon palette is pinned to the accent because Starlight's staggered grid rotates through colours including purple. Package URLs now point at the Gitea repo and this site.
93 lines
2.7 KiB
JavaScript
93 lines
2.7 KiB
JavaScript
// mcqemu docs — Starlight with a diataxis-shaped sidebar.
|
|
//
|
|
// Telemetry and devToolbar are off per project convention. The HMR block
|
|
// matters when the dev server runs behind Caddy: Vite's WebSocket needs an
|
|
// explicit host, protocol and clientPort or HMR drops every few seconds
|
|
// with "server connection lost".
|
|
//
|
|
// DOMAIN drives both the canonical site URL and the HMR host, so the same
|
|
// image serves mcqemu.warehack.ing (prod) and mcqemu.l.warehack.ing (dev).
|
|
|
|
import mdx from "@astrojs/mdx";
|
|
import sitemap from "@astrojs/sitemap";
|
|
import starlight from "@astrojs/starlight";
|
|
import { defineConfig } from "astro/config";
|
|
import remarkGfm from "remark-gfm";
|
|
import starlightLinksValidator from "starlight-links-validator";
|
|
|
|
const domain = process.env.DOMAIN ?? "mcqemu.warehack.ing";
|
|
|
|
export default defineConfig({
|
|
site: `https://${domain}`,
|
|
telemetry: false,
|
|
devToolbar: { enabled: false },
|
|
|
|
vite: {
|
|
server: {
|
|
host: "0.0.0.0",
|
|
hmr: {
|
|
host: domain,
|
|
protocol: "wss",
|
|
clientPort: 443,
|
|
},
|
|
},
|
|
},
|
|
|
|
integrations: [
|
|
starlight({
|
|
title: "mcqemu",
|
|
description:
|
|
"MCP server for QEMU: VM lifecycle, disposable sandboxes, live snapshots, guest-agent access, and screenshot-driven control.",
|
|
favicon: "/favicon.svg",
|
|
customCss: ["./src/styles/theme.css"],
|
|
|
|
social: [
|
|
{
|
|
icon: "seti:git",
|
|
label: "Source",
|
|
href: "https://git.supported.systems/warehack.ing/mcqemu",
|
|
},
|
|
],
|
|
|
|
// Diataxis order: orientation, then learning, then doing, then
|
|
// looking up, then understanding.
|
|
// Starlight v0.39+ needs {label, items:[{autogenerate}]}; the inline
|
|
// {label, autogenerate} shorthand was removed.
|
|
sidebar: [
|
|
{
|
|
label: "Start here",
|
|
items: [{ label: "What is mcqemu?", slug: "overview" }],
|
|
},
|
|
{
|
|
label: "Tutorial",
|
|
items: [{ autogenerate: { directory: "tutorial" } }],
|
|
},
|
|
{
|
|
label: "How-to",
|
|
items: [{ autogenerate: { directory: "how-to" } }],
|
|
},
|
|
{
|
|
label: "Reference",
|
|
items: [{ autogenerate: { directory: "reference" } }],
|
|
},
|
|
{
|
|
label: "Explanation",
|
|
items: [{ autogenerate: { directory: "explanation" } }],
|
|
},
|
|
],
|
|
|
|
plugins: [
|
|
// Broken internal links fail the build instead of shipping.
|
|
starlightLinksValidator({ errorOnRelativeLinks: false }),
|
|
],
|
|
|
|
pagination: true,
|
|
lastUpdated: true,
|
|
}),
|
|
// Astro enables GFM for .md, but the MDX pipeline does not inherit it,
|
|
// so tables render as run-together paragraphs without this.
|
|
mdx({ remarkPlugins: [remarkGfm] }),
|
|
sitemap(),
|
|
],
|
|
});
|