diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 67f2f9f3..14ee2c02 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -79,10 +79,24 @@ export default defineConfig({ href: "https://github.com/archgate/cli", }, ], + components: { + Head: "./src/components/HeadSEO.astro", + }, editLink: { baseUrl: "https://github.com/archgate/cli/edit/main/docs/", }, + favicon: "/favicon.svg", head: [ + // ── Favicon ─────────────────────────────────────────────── + { + tag: "link", + attrs: { + rel: "icon", + type: "image/svg+xml", + href: "/favicon.svg", + }, + }, + // ── Analytics ───────────────────────────────────────────── { tag: "script", attrs: { @@ -91,6 +105,91 @@ export default defineConfig({ "data-cf-beacon": '{"token": "cee359c05ecc496aabc4f40f05302a03"}', }, }, + // ── Open Graph image ────────────────────────────────────── + { + tag: "meta", + attrs: { + property: "og:image", + content: "https://cli.archgate.dev/og-image.png", + }, + }, + { + tag: "meta", + attrs: { property: "og:image:width", content: "1200" }, + }, + { + tag: "meta", + attrs: { property: "og:image:height", content: "630" }, + }, + { + tag: "meta", + attrs: { + property: "og:image:alt", + content: + "Archgate — Architecture Decision Records as Executable Rules", + }, + }, + // ── Twitter / X card ────────────────────────────────────── + { + tag: "meta", + attrs: { + name: "twitter:image", + content: "https://cli.archgate.dev/og-image.png", + }, + }, + // ── Additional meta ─────────────────────────────────────── + { + tag: "meta", + attrs: { name: "author", content: "Archgate" }, + }, + { + tag: "meta", + attrs: { name: "theme-color", content: "#6366f1" }, + }, + { + tag: "meta", + attrs: { + name: "keywords", + content: + "archgate, architecture decision records, ADR, executable rules, code governance, AI governance, TypeScript rules, CLI, compliance automation, MCP server", + }, + }, + // ── JSON-LD: WebSite ────────────────────────────────────── + { + tag: "script", + attrs: { type: "application/ld+json" }, + content: JSON.stringify({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "Archgate CLI Documentation", + url: "https://cli.archgate.dev", + description: + "Documentation for Archgate — enforce Architecture Decision Records as executable TypeScript rules for automated code governance.", + inLanguage: ["en", "pt-BR"], + }), + }, + // ── JSON-LD: SoftwareApplication ────────────────────────── + { + tag: "script", + attrs: { type: "application/ld+json" }, + content: JSON.stringify({ + "@context": "https://schema.org", + "@type": "SoftwareApplication", + name: "Archgate CLI", + applicationCategory: "DeveloperApplication", + operatingSystem: "macOS, Linux, Windows", + offers: { "@type": "Offer", price: "0", priceCurrency: "USD" }, + url: "https://cli.archgate.dev", + downloadUrl: "https://www.npmjs.com/package/archgate", + description: + "CLI tool that enforces Architecture Decision Records (ADRs) as executable TypeScript rules for automated code governance.", + author: { + "@type": "Organization", + name: "Archgate", + url: "https://archgate.dev", + }, + }), + }, ], sidebar: [ { diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg new file mode 100644 index 00000000..69036679 --- /dev/null +++ b/docs/public/favicon.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/docs/public/llms.txt b/docs/public/llms.txt new file mode 100644 index 00000000..7c8c1d0d --- /dev/null +++ b/docs/public/llms.txt @@ -0,0 +1,45 @@ +# Archgate CLI + +> Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs). It combines human-readable documentation with machine-checkable TypeScript rules to enforce architectural decisions across codebases — for both humans and AI agents. + +Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdown files with YAML frontmatter that describe architectural decisions. Companion `.rules.ts` files contain automated TypeScript checks that run against the codebase and report violations with file paths and line numbers. + +## Key capabilities + +- **Executable rules**: Write compliance rules in TypeScript. Archgate runs them against your codebase and reports violations with file paths and line numbers. +- **CI integration**: Wire `archgate check` into any CI/CD pipeline. Exit code 1 blocks merges when rules are violated. +- **AI-aware governance**: The MCP server gives AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after. +- **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based governance skills. +- **Self-governance**: Archgate governs its own development using the same tool. + +## Installation + +Available via npm (`npm install -g archgate`), Homebrew, or standalone binary for macOS, Linux, and Windows. + +## Documentation + +- [Getting Started — Installation](https://cli.archgate.dev/getting-started/installation/): Install on macOS, Linux, or Windows via npm, Homebrew, or standalone binary. +- [Getting Started — Quick Start](https://cli.archgate.dev/getting-started/quick-start/): Set up Archgate in under 5 minutes with your first ADR and rule. +- [Core Concepts — ADRs](https://cli.archgate.dev/concepts/adrs/): How Architecture Decision Records work as both documentation and executable rules. +- [Core Concepts — Rules](https://cli.archgate.dev/concepts/rules/): The TypeScript rule system that turns ADR decisions into automated compliance checks. +- [Core Concepts — Domains](https://cli.archgate.dev/concepts/domains/): Organize ADRs by domain for targeted governance. +- [Guide — Writing ADRs](https://cli.archgate.dev/guides/writing-adrs/): Complete guide to writing effective ADRs with YAML frontmatter and markdown structure. +- [Guide — Writing Rules](https://cli.archgate.dev/guides/writing-rules/): Write TypeScript rules using the defineRules API with file matching and violation reporting. +- [Guide — CI Integration](https://cli.archgate.dev/guides/ci-integration/): Add Archgate checks to GitHub Actions, GitLab CI, or any pipeline. +- [Guide — Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a governance workflow that reads ADRs, validates code, and captures patterns. +- [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code. +- [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI. +- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills. +- [Guide — MCP Server](https://cli.archgate.dev/guides/mcp-server/): Give AI agents live access to ADRs via the Model Context Protocol. +- [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit. +- [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more. +- [Reference — MCP Tools](https://cli.archgate.dev/reference/mcp-tools/): API reference for adr_list, adr_read, check_compliance, and review_context. +- [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for defineRules, RuleContext, and violation reporting. +- [Reference — ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs. +- [Examples — Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more. + +## Optional + +- [GitHub Repository](https://github.com/archgate/cli) +- [Editor Plugin Beta](https://plugins.archgate.dev) +- [npm Package](https://www.npmjs.com/package/archgate) diff --git a/docs/public/og-image.png b/docs/public/og-image.png new file mode 100644 index 00000000..c794aaad Binary files /dev/null and b/docs/public/og-image.png differ diff --git a/docs/public/og-image.svg b/docs/public/og-image.svg new file mode 100644 index 00000000..b94b33bb --- /dev/null +++ b/docs/public/og-image.svg @@ -0,0 +1,36 @@ + + + + + + + + + + + + + archgate + + + + + Executable Architecture Decision Records + + + + + Write an ADR once. Enforce it everywhere. + + + Govern AI agents and humans with the same rules. + + + + + archgate.dev + + + + + diff --git a/docs/public/robots.txt b/docs/public/robots.txt new file mode 100644 index 00000000..ddaa7724 --- /dev/null +++ b/docs/public/robots.txt @@ -0,0 +1,8 @@ +# Archgate CLI Documentation — https://cli.archgate.dev +# Allow all search engines and AI crawlers full access + +User-agent: * +Allow: / + +# Sitemap location +Sitemap: https://cli.archgate.dev/sitemap-index.xml diff --git a/docs/scripts/generate-og-image.ts b/docs/scripts/generate-og-image.ts new file mode 100644 index 00000000..80675970 --- /dev/null +++ b/docs/scripts/generate-og-image.ts @@ -0,0 +1,21 @@ +/** + * Generates the default Open Graph image (1200x630 PNG) for social sharing. + * Reads the branded SVG from the website repo and converts it to PNG via sharp. + * + * Run: bun run docs/scripts/generate-og-image.ts + */ +import sharp from "sharp"; +import { join } from "node:path"; +import { readFileSync } from "node:fs"; + +const svgPath = join(import.meta.dirname, "..", "public", "og-image.svg"); +const outputPath = join(import.meta.dirname, "..", "public", "og-image.png"); + +const svg = readFileSync(svgPath, "utf-8"); + +await sharp(Buffer.from(svg)) + .resize(1200, 630) + .png({ quality: 90 }) + .toFile(outputPath); + +console.log(`Generated OG image: ${outputPath}`); diff --git a/docs/src/components/HeadSEO.astro b/docs/src/components/HeadSEO.astro new file mode 100644 index 00000000..0096ebc3 --- /dev/null +++ b/docs/src/components/HeadSEO.astro @@ -0,0 +1,102 @@ +--- +/** + * Custom Starlight Head override that injects structured data (JSON-LD) + * into every page: + * + * 1. BreadcrumbList — auto-generated from the URL path + * 2. TechArticle — for all documentation pages (not splash/home) + * + * Registered via `components: { Head }` in astro.config.mjs. + */ +import Default from "@astrojs/starlight/components/Head.astro"; + +const route = Astro.locals.starlightRoute; +const siteUrl = + Astro.site?.href?.replace(/\/$/, "") ?? "https://cli.archgate.dev"; +const pathname = Astro.url.pathname; +const pageUrl = `${siteUrl}${pathname}`; + +// Guard: 404 and other non-content pages may not have route data. +const hasRoute = route?.entry?.data !== undefined && route?.entry?.data !== null; +const title = hasRoute ? route.entry.data.title : undefined; +const description = hasRoute ? route.entry.data.description : undefined; +const template = hasRoute ? route.entry.data.template : undefined; + +// ── BreadcrumbList ──────────────────────────────────────────────── +// Build breadcrumbs from the URL path segments. +const segments = pathname + .split("/") + .filter((s: string) => s.length > 0); +const breadcrumbItems: Array<{ + "@type": string; + position: number; + name: string; + item: string; +}> = [ + { "@type": "ListItem", position: 1, name: "Home", item: `${siteUrl}/` }, +]; + +if (hasRoute && segments.length > 0) { + let cumulativePath = ""; + for (let i = 0; i < segments.length; i++) { + cumulativePath += `/${segments[i]}`; + const name = + i === segments.length - 1 + ? title + : segments[i] + .replaceAll("-", " ") + .replaceAll(/\b\w/g, (c: string) => c.toUpperCase()); + breadcrumbItems.push({ + "@type": "ListItem", + position: i + 2, + name: name ?? segments[i], + item: `${siteUrl}${cumulativePath}/`, + }); + } +} + +const breadcrumbLd = + breadcrumbItems.length > 1 + ? { + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: breadcrumbItems, + } + : null; + +// ── TechArticle (all doc pages except splash/home) ──────────────── +const isSplash = template === "splash"; +const articleLd = + hasRoute && !isSplash + ? { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: title, + description, + url: pageUrl, + inLanguage: route.lang ?? "en", + isPartOf: { + "@type": "WebSite", + name: "Archgate CLI Documentation", + url: siteUrl, + }, + publisher: { + "@type": "Organization", + name: "Archgate", + url: "https://archgate.dev", + }, + } + : null; +--- + + + +{/* BreadcrumbList — pages with path segments */} +{breadcrumbLd && ( +