feat: documentation site

Docusaurus 3 docs-only site at docsite/, served statically by nginx under /docs on the marketing host. Covers getting started (self-hosted install through first server and first licence), the control plane, Vantage HQ, a reference section and operations. Wired into docker-compose.site.yml as docsite (3005:80) and into the image build workflow, rebuilding on its own directory only. Never added to the self-hosted compose file.
2026-07-28 15:46:33 +01:00
parent d9945882e5
commit f46fb7fc0e
46 changed files with 23697 additions and 2 deletions
@@ -0,0 +1,123 @@
+import type * as Preset from "@docusaurus/preset-classic";
+import type { Config } from "@docusaurus/types";
+import { themes as prismThemes } from "prism-react-renderer";
+
+// Served as a path on the marketing host (vantage.hostxtra.co.uk/docs), routed
+// by its own Nginx Proxy Manager location rather than by site/. A path and not
+// a subdomain on purpose: *.vantage.hostxtra.co.uk is the per-tenant instance
+// namespace, and APP_ROOT_LABEL resolves an org from the label before
+// "vantage", so a docs. label there would be read as a tenant slug.
+//
+// DOCS_BASE_URL has to agree with three things at once: the NPM location, the
+// directory the runtime image copies the build into, and this value. When they
+// disagree the HTML still loads and every asset 404s.
+const url = process.env.DOCS_URL || "https://vantage.hostxtra.co.uk";
+const baseUrl = process.env.DOCS_BASE_URL || "/docs/";
+const appUrl = process.env.APP_URL || "https://vantage.hostxtra.co.uk";
+const hqUrl = process.env.HQ_URL || "https://vantage-hq.hostxtra.co.uk";
+
+const config: Config = {
+    title: "Vantage Docs",
+    tagline: "Fleet management for servers you actually own",
+    favicon: "img/favicon.svg",
+
+    url,
+    baseUrl,
+
+    organizationName: "hostxtra",
+    projectName: "vantage",
+
+    onBrokenLinks: "throw",
+    onBrokenAnchors: "throw",
+
+    i18n: { defaultLocale: "en", locales: ["en"] },
+
+    markdown: {
+        mermaid: true,
+        hooks: { onBrokenMarkdownLinks: "throw" },
+    },
+    themes: [
+        "@docusaurus/theme-mermaid",
+        [
+            // Compile-time index served from this origin. No Algolia account,
+            // no external host, nothing to key or rotate.
+            "@easyops-cn/docusaurus-search-local",
+            {
+                hashed: true,
+                indexBlog: false,
+                docsRouteBasePath: "/",
+                highlightSearchTermsOnTargetPage: true,
+            },
+        ],
+    ],
+
+    presets: [
+        [
+            "classic",
+            {
+                docs: {
+                    // Docs-only mode: the documentation is the site.
+                    routeBasePath: "/",
+                    sidebarPath: "./sidebars.ts",
+                },
+                blog: false,
+                theme: { customCss: "./src/css/custom.css" },
+            } satisfies Preset.Options,
+        ],
+    ],
+
+    themeConfig: {
+        colorMode: {
+            // Light default, matching site/ and adminsite/. web/ is the only
+            // app locked to dark, and that contrast is deliberate.
+            defaultMode: "light",
+            respectPrefersColorScheme: true,
+        },
+        navbar: {
+            // Wordmark only. The logo mark is drawn with currentColor in
+            // site/components/Logo.tsx, which an <img> src cannot inherit, and
+            // baking a fill into the file would mean a hex that stops tracking
+            // the theme.
+            title: "Vantage",
+            items: [
+                {
+                    type: "docSidebar",
+                    sidebarId: "docs",
+                    position: "left",
+                    label: "Documentation",
+                },
+                { href: appUrl, label: "Control plane", position: "right" },
+                { href: hqUrl, label: "Vantage HQ", position: "right" },
+            ],
+        },
+        footer: {
+            style: "light",
+            links: [
+                {
+                    title: "Documentation",
+                    items: [
+                        { label: "Getting started", to: "/getting-started/what-is-vantage" },
+                        { label: "Vantage", to: "/vantage/servers" },
+                        { label: "Vantage HQ", to: "/hq/accounts-and-signup" },
+                        { label: "Reference", to: "/reference/environment-variables" },
+                    ],
+                },
+                {
+                    title: "Product",
+                    items: [
+                        { label: "Control plane", href: appUrl },
+                        { label: "Vantage HQ", href: hqUrl },
+                    ],
+                },
+            ],
+            copyright: `© ${new Date().getFullYear()} HostXtra.`,
+        },
+        prism: {
+            theme: prismThemes.github,
+            darkTheme: prismThemes.dracula,
+            additionalLanguages: ["bash", "powershell", "yaml", "json", "protobuf", "nginx"],
+        },
+    } satisfies Preset.ThemeConfig,
+};
+
+export default config;