@hgdc/docs 0.0.0-stage → 0.1.1

package/src/integration.ts

@@ -0,0 +1,229 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { unified } from "@astrojs/markdown-remark"
+import starlight from "@astrojs/starlight"
+import type { AstroIntegration, AstroUserConfig } from "astro"
+
+import { remarkAutoImport } from "./build/auto-import.ts"
+import { publicFiles } from "./build/public-files.ts"
+import { writeMachineReadable } from "./build/outputs.ts"
+import { parseDocsConfig, withHostProject, type DocsConfig } from "./core/config.ts"
+import { missingPages, normalizeNavigation, pageToSlug, type NavItem, type NavTree } from "./core/navigation.ts"
+import { themeCss, themeFor } from "./core/theme.ts"
+
+/** Où lire la doc du client et où écrire le site : posé par la CLI `hgdc-docs`. */
+export type SiteOptions = {
+  contentDir: string
+  outDir: string
+  /** Adresse publique du site, pour les liens absolus de `llms.txt` et le sitemap. */
+  site: string | null
+  /** API de l'assistant (console HGDC Docs). */
+  apiEndpoint: string
+  /** Projet de la console annoncé par HGDC Host (`HGDC_DOCS_PROJECT`), si docs.json n'en a pas. */
+  project: string | null
+}
+
+export const DEFAULT_API = "https://docs.hgdc.ch"
+const here = dirname(fileURLToPath(import.meta.url))
+const file = (path: string) => resolve(here, path)
+
+export function readSiteOptions(env: NodeJS.ProcessEnv = process.env): SiteOptions {
+  const contentDir = resolve(env.HGDC_DOCS_DIR ?? process.cwd())
+  const vercelUrl = env.VERCEL_PROJECT_PRODUCTION_URL ? `https://${env.VERCEL_PROJECT_PRODUCTION_URL}` : null
+  return {
+    contentDir,
+    outDir: resolve(env.HGDC_DOCS_OUT ?? join(contentDir, "dist")),
+    site: env.HGDC_DOCS_SITE ?? vercelUrl,
+    apiEndpoint: env.HGDC_DOCS_API ?? DEFAULT_API,
+    project: env.HGDC_DOCS_PROJECT ?? null,
+  }
+}
+
+export class DocsConfigError extends Error {}
+
+export function loadDocsConfig(contentDir: string, hostProject: string | null = null): DocsConfig {
+  const path = join(contentDir, "docs.json")
+  if (!existsSync(path)) throw new DocsConfigError(`Aucun docs.json dans ${contentDir}. Crée-le à la racine de la doc.`)
+  const parsed = parseDocsConfig(readFileSync(path, "utf8"))
+  const result = parsed.ok ? withHostProject(parsed.config, hostProject ?? undefined) : parsed
+  if (!result.ok) throw new DocsConfigError(`docs.json invalide :\n- ${result.errors.join("\n- ")}`)
+  return result.config
+}
+
+/** Ce que les composants du modèle lisent par `virtual:hgdc-docs/config`. */
+export type VirtualConfig = {
+  config: DocsConfig
+  tree: NavTree
+  apiEndpoint: string
+  site: string | null
+}
+
+const IGNORED_DIRS = new Set(["node_modules", "dist", ".hgdc-docs", ".git", ".github", ".vercel"])
+
+function collectPublic(contentDir: string, declared: ReadonlyArray<string>): string {
+  const target = join(contentDir, ".hgdc-docs", "public")
+  rmSync(target, { recursive: true, force: true })
+  mkdirSync(target, { recursive: true })
+  for (const file of publicFiles(contentDir, declared)) cpSync(file.from, join(target, file.to))
+  return target
+}
+
+/** Pages du dépôt (`guides/publier`) et leur `sidebarTitle` éventuel (champ Mintlify). */
+function scanPages(contentDir: string): Map<string, string | null> {
+  const pages = new Map<string, string | null>()
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      if (name.startsWith(".") || IGNORED_DIRS.has(name)) continue
+      const path = join(dir, name)
+      if (statSync(path).isDirectory()) walk(path)
+      else if (/\.mdx?$/.test(name) && !name.startsWith("_")) {
+        const page = relative(contentDir, path)
+          .replaceAll("\\", "/")
+          .replace(/\.mdx?$/, "")
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(path, "utf8"))?.[1] ?? ""
+        const label = /^sidebarTitle:\s*["']?(.+?)["']?\s*$/m.exec(frontmatter)?.[1] ?? null
+        pages.set(pageToSlug(page), label)
+      }
+    }
+  }
+  walk(contentDir)
+  return pages
+}
+
+type SidebarItem = { slug: string; label?: string } | { label: string; collapsed: boolean; items: Array<SidebarItem> }
+
+function sidebarItems(items: Array<NavItem>, labels: ReadonlyMap<string, string | null>): Array<SidebarItem> {
+  return items.map((item) => {
+    if (item.type === "group")
+      return { label: item.label, collapsed: !item.expanded, items: sidebarItems(item.items, labels) }
+    const slug = pageToSlug(item.page)
+    const label = labels.get(slug)
+    return label ? { slug, label } : { slug }
+  })
+}
+
+/**
+ * Une entrée de premier niveau par couple (version, onglet), dans l'ordre de l'arbre ;
+ * `route-data.ts` ne garde ensuite que celle de la page affichée.
+ */
+export function starlightSidebar(
+  tree: NavTree,
+  labels: ReadonlyMap<string, string | null> = new Map(),
+): Array<SidebarItem> {
+  const sections = tree.versions.flatMap((version) => version.tabs)
+  if (sections.length === 1) return sidebarItems(sections[0]!.items, labels)
+  return tree.versions.flatMap((version) =>
+    version.tabs.map((tab) => ({
+      label: [version.label, tab.label].filter(Boolean).join(" · ") || "Documentation",
+      collapsed: false,
+      items: sidebarItems(tab.items, labels),
+    })),
+  )
+}
+
+const SOCIAL_ICONS = new Set([
+  "github",
+  "gitlab",
+  "linkedin",
+  "x.com",
+  "mastodon",
+  "discord",
+  "youtube",
+  "instagram",
+  "bluesky",
+])
+
+function virtualConfigPlugin(data: VirtualConfig) {
+  const id = "virtual:hgdc-docs/config"
+  return {
+    name: "hgdc-docs-config",
+    resolveId: (source: string) => (source === id ? `\0${id}` : undefined),
+    load: (source: string) => (source === `\0${id}` ? `export default ${JSON.stringify(data)}` : undefined),
+  }
+}
+
+function machineReadableOutputs(data: VirtualConfig, options: SiteOptions): AstroIntegration {
+  return {
+    name: "hgdc-docs-outputs",
+    hooks: {
+      "astro:build:done": async ({ dir, pages, logger }) => {
+        const written = await writeMachineReadable({
+          outDir: fileURLToPath(dir),
+          pathnames: pages.map((page) => page.pathname),
+          config: data.config,
+          tree: data.tree,
+          site: options.site,
+        })
+        logger.info(`llms.txt, llms-full.txt, ${written.pages} pages Markdown et le corpus de l'assistant écrits.`)
+        // Le build tourne dans le paquet, où ses dépendances se résolvent quel que soit le
+        // gestionnaire du client (npm, pnpm, bun isolé), puis le site seul est copié chez lui.
+        rmSync(options.outDir, { recursive: true, force: true })
+        cpSync(fileURLToPath(dir), options.outDir, { recursive: true, filter: (path) => !path.includes(".prerender") })
+        logger.info(`Site écrit dans ${options.outDir}`)
+      },
+    },
+  }
+}
+
+export function createAstroConfig(options: SiteOptions = readSiteOptions()): AstroUserConfig {
+  const config = loadDocsConfig(options.contentDir, options.project)
+  const tree = normalizeNavigation(config)
+  const pages = scanPages(options.contentDir)
+  const missing = missingPages(tree, new Set(pages.keys()))
+  if (missing.length)
+    throw new DocsConfigError(
+      `docs.json cite des pages absentes du dossier :\n- ${missing.map((page) => `${page}.mdx`).join("\n- ")}`,
+    )
+  const data: VirtualConfig = { config, tree, apiEndpoint: options.apiEndpoint, site: options.site }
+  const theme = themeFor(config.colors?.primary, config.colors?.dark)
+  const logo = typeof config.logo === "string" ? { light: config.logo } : config.logo
+  const asset = (path: string) => join(options.contentDir, path.replace(/^\//, ""))
+  const social = Object.entries(config.footer?.socials ?? {})
+    .filter(([icon]) => SOCIAL_ICONS.has(icon))
+    .map(([icon, href]) => ({ icon: (icon === "x.com" ? "x.com" : icon) as "github", label: icon, href }))
+
+  return {
+    root: file("../template"),
+    srcDir: file("../template/src"),
+    publicDir: collectPublic(
+      options.contentDir,
+      [logo?.light, logo?.dark, config.favicon].filter((p): p is string => Boolean(p)),
+    ),
+    outDir: file("../template/.build"),
+    cacheDir: join(options.contentDir, ".hgdc-docs", "cache"),
+    site: options.site ?? undefined,
+    trailingSlash: "always",
+    markdown: { processor: unified({ remarkPlugins: [remarkAutoImport] }) },
+    vite: {
+      plugins: [virtualConfigPlugin(data)],
+      server: { fs: { allow: [options.contentDir, file("..")] } },
+    },
+    integrations: [
+      starlight({
+        title: config.name,
+        description: config.description,
+        locales: { root: { label: "Français", lang: config.language === "fr" ? "fr-CH" : config.language } },
+        logo: logo
+          ? { light: asset(logo.light), dark: asset(logo.dark ?? logo.light), replacesTitle: false }
+          : undefined,
+        favicon: config.favicon ?? "/favicon.svg",
+        social,
+        sidebar: starlightSidebar(tree, pages),
+        customCss: [file("./styles/theme.css")],
+        head: [{ tag: "style", content: themeCss(theme) }],
+        routeMiddleware: file("./overrides/route-data.ts"),
+        components: {
+          Head: file("./overrides/Head.astro"),
+          Sidebar: file("./overrides/Sidebar.astro"),
+          PageTitle: file("./overrides/PageTitle.astro"),
+          PageFrame: file("./overrides/PageFrame.astro"),
+        },
+        expressiveCode: { themes: ["github-dark-default", "github-light-default"] },
+        pagination: true,
+      }),
+      machineReadableOutputs(data, options),
+    ],
+  }
+}

package/src/locals.d.ts

@@ -0,0 +1,6 @@
+declare namespace App {
+  interface Locals {
+    /** Index de la section (version, onglet) de la page, posé par `route-data.ts`. */
+    hgdcSection?: number
+  }
+}

package/src/overrides/Assistant.astro

@@ -0,0 +1,72 @@
+---
+import data from "virtual:hgdc-docs/config"
+
+// Widget de l'assistant : panneau latéral non modal (la page reste lisible), plein écran
+// sur téléphone. Logique dans `../widget/client.ts`.
+const endpoint = new URL("/api/v1/ask", data.config.assistant?.endpoint ?? data.apiEndpoint).toString()
+---
+
+<hgdc-assistant data-endpoint={endpoint} data-project={data.config.project} data-name={data.config.name}>
+  <button type="button" class="hgdc-launcher" data-open aria-haspopup="dialog" aria-expanded="false">
+    <svg aria-hidden="true" viewBox="0 0 24 24" width="18" height="18">
+      <path d="M12 3l1.9 4.6L18.5 9.5l-4.6 1.9L12 16l-1.9-4.6L5.5 9.5l4.6-1.9z" fill="currentColor"></path>
+      <path d="M18.5 15l.8 1.9 1.9.8-1.9.8-.8 1.9-.8-1.9-1.9-.8 1.9-.8z" fill="currentColor"></path>
+    </svg>
+    <span>Demander à l'IA</span>
+    <kbd class="hgdc-kbd" data-shortcut aria-hidden="true">Ctrl I</kbd>
+  </button>
+
+  <section class="hgdc-panel" role="dialog" aria-modal="false" aria-labelledby="hgdc-assistant-title" hidden>
+    <header class="hgdc-panel__header">
+      <div>
+        <h2 id="hgdc-assistant-title">Assistant</h2>
+        <p>Répond à partir de cette documentation, avec ses sources.</p>
+      </div>
+      <div class="hgdc-panel__tools">
+        <button type="button" class="hgdc-icon-button" data-reset aria-label="Nouvelle conversation" hidden>
+          <svg aria-hidden="true" viewBox="0 0 24 24" width="18" height="18"
+            ><path d="M4 12a8 8 0 1 0 2.3-5.7M4 4v4h4" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"
+            ></path></svg
+          >
+        </button>
+        <button type="button" class="hgdc-icon-button" data-close aria-label="Fermer l'assistant">
+          <svg aria-hidden="true" viewBox="0 0 24 24" width="18" height="18"
+            ><path d="M6 6l12 12M18 6 6 18" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"
+            ></path></svg
+          >
+        </button>
+      </div>
+    </header>
+
+    <div class="hgdc-panel__body" data-log aria-live="polite">
+      <div class="hgdc-empty" data-empty>
+        <p class="hgdc-empty__title">Pose ta question sur {data.config.name}.</p>
+        <p>
+          Je cherche dans les pages de cette documentation et je cite mes sources. Si la réponse n'y est pas, je te le
+          dis.
+        </p>
+      </div>
+    </div>
+
+    <form class="hgdc-panel__form" data-form>
+      <label class="sr-only" for="hgdc-question">Ta question</label>
+      <textarea id="hgdc-question" data-input rows="1" maxlength="1000" placeholder="Comment publier ma doc ?" required
+      ></textarea>
+      <button type="submit" class="hgdc-send" data-send aria-label="Envoyer la question">
+        <svg aria-hidden="true" viewBox="0 0 24 24" width="18" height="18"
+          ><path d="M12 19V5M5 12l7-7 7 7" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"
+          ></path></svg
+        >
+      </button>
+    </form>
+    <p class="hgdc-panel__note">
+      Réponses générées par IA (Claude, d'Anthropic), à vérifier. Les questions sont conservées 90 jours pour améliorer cette documentation.
+    </p>
+  </section>
+</hgdc-assistant>
+
+<script>
+  import { defineAssistant } from "../widget/client.ts"
+
+  defineAssistant()
+</script>

package/src/overrides/Head.astro

@@ -0,0 +1,12 @@
+---
+import Default from "@astrojs/starlight/components/Head.astro"
+
+import { markdownPath } from "../core/llms.ts"
+
+// llmstxt.org : chaque page annonce sa version Markdown et l'index qui la décrit.
+const markdown = markdownPath(Astro.url.pathname)
+---
+
+<Default><slot /></Default>
+<link rel="alternate" type="text/markdown" href={markdown} />
+<link rel="describedby" type="text/markdown" href="/llms.txt" />

package/src/overrides/PageFrame.astro

@@ -0,0 +1,15 @@
+---
+import Default from "@astrojs/starlight/components/PageFrame.astro"
+import data from "virtual:hgdc-docs/config"
+
+import Assistant from "./Assistant.astro"
+
+const assistant = data.config.project && data.config.assistant?.enabled !== false
+---
+
+<Default>
+  <slot name="header" slot="header" />
+  <slot name="sidebar" slot="sidebar" />
+  <slot />
+</Default>
+{assistant && <Assistant />}

package/src/overrides/PageTitle.astro

@@ -0,0 +1,94 @@
+---
+import Default from "@astrojs/starlight/components/PageTitle.astro"
+import data from "virtual:hgdc-docs/config"
+
+import { markdownPath } from "../core/llms.ts"
+
+const markdown = markdownPath(Astro.url.pathname)
+const assistant = Boolean(data.config.project) && data.config.assistant?.enabled !== false
+---
+
+<div class="hgdc-title">
+  <Default><slot /></Default>
+  <div class="hgdc-page-actions not-content" data-hgdc-skip data-pagefind-ignore>
+    <button type="button" class="hgdc-action" data-hgdc-copy={markdown}>
+      <svg aria-hidden="true" viewBox="0 0 24 24" width="16" height="16"
+        ><rect x="8" y="8" width="12" height="12" rx="3" fill="none" stroke="currentColor" stroke-width="1.8"
+        ></rect><path d="M16 8V6a2 2 0 0 0-2-2H6a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h2" fill="none" stroke="currentColor" stroke-width="1.8"
+        ></path></svg
+      >
+      <span data-label>Copier pour un LLM</span>
+    </button>
+    <details class="hgdc-menu">
+      <summary class="hgdc-action hgdc-action--icon" aria-label="Autres formats de la page">
+        <svg aria-hidden="true" viewBox="0 0 24 24" width="16" height="16"
+          ><path d="m6 9 6 6 6-6" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"></path></svg
+        >
+      </summary>
+      <ul class="hgdc-menu__list">
+        <li><a href={markdown}>Voir en Markdown</a></li>
+        <li><a data-hgdc-open="claude" href="https://claude.ai/new" target="_blank" rel="noopener">Ouvrir dans Claude</a></li>
+        <li><a data-hgdc-open="chatgpt" href="https://chatgpt.com/" target="_blank" rel="noopener">Ouvrir dans ChatGPT</a></li>
+        <li><a href="/llms.txt">Index pour les agents (llms.txt)</a></li>
+      </ul>
+    </details>
+    {
+      assistant && (
+        <button type="button" class="hgdc-action" data-hgdc-ask>
+          <svg aria-hidden="true" viewBox="0 0 24 24" width="16" height="16">
+            <path d="M12 3l1.9 4.6L18.5 9.5l-4.6 1.9L12 16l-1.9-4.6L5.5 9.5l4.6-1.9z" fill="currentColor" />
+          </svg>
+          <span>Demander à l'assistant</span>
+        </button>
+      )
+    }
+    <span class="sr-only" role="status" aria-live="polite" data-hgdc-copy-status></span>
+  </div>
+</div>
+
+<script>
+  const status = document.querySelector<HTMLElement>("[data-hgdc-copy-status]")
+
+  for (const button of document.querySelectorAll<HTMLButtonElement>("[data-hgdc-copy]")) {
+    const label = button.querySelector<HTMLElement>("[data-label]")!
+    button.addEventListener("click", async () => {
+      const done = (text: string) => {
+        label.textContent = text
+        if (status) status.textContent = text
+        setTimeout(() => (label.textContent = "Copier pour un LLM"), 2000)
+      }
+      try {
+        const response = await fetch(button.dataset.hgdcCopy!)
+        if (!response.ok) throw new Error(String(response.status))
+        await navigator.clipboard.writeText(await response.text())
+        done("Page copiée")
+      } catch {
+        done("Copie impossible")
+      }
+    })
+  }
+
+  // « Ouvrir dans… » : l'assistant externe lit la version Markdown de cette page.
+  const markdownUrl = new URL(document.querySelector<HTMLElement>("[data-hgdc-copy]")!.dataset.hgdcCopy!, location.href)
+  const prompt = `Lis ${markdownUrl.href} et réponds à mes questions sur cette page.`
+  for (const link of document.querySelectorAll<HTMLAnchorElement>("[data-hgdc-open]")) {
+    const base = link.dataset.hgdcOpen === "claude" ? "https://claude.ai/new" : "https://chatgpt.com/"
+    link.href = `${base}?q=${encodeURIComponent(prompt)}`
+  }
+
+  // Le menu se ferme au clic extérieur et à Échap, comme un menu natif.
+  for (const menu of document.querySelectorAll<HTMLDetailsElement>(".hgdc-menu")) {
+    document.addEventListener("click", (event) => {
+      if (menu.open && !menu.contains(event.target as Node)) menu.open = false
+    })
+    menu.addEventListener("keydown", (event) => {
+      if (event.key === "Escape" && menu.open) {
+        menu.open = false
+        menu.querySelector("summary")?.focus()
+      }
+    })
+  }
+
+  for (const button of document.querySelectorAll("[data-hgdc-ask]"))
+    button.addEventListener("click", () => document.dispatchEvent(new CustomEvent("hgdc:assistant-open")))
+</script>

package/src/overrides/Sidebar.astro

@@ -0,0 +1,60 @@
+---
+import Default from "@astrojs/starlight/components/Sidebar.astro"
+import data from "virtual:hgdc-docs/config"
+
+import { pagesOf, pageToPath } from "../core/navigation.ts"
+
+// Onglets et versions de docs.json, en tête de la sidebar : visibles sur ordinateur et dans
+// le menu mobile, sans toucher à la hauteur de l'en-tête de Starlight.
+const sections = data.tree.versions.flatMap((version) => version.tabs.map((tab) => ({ version, tab })))
+const index = Astro.locals.hgdcSection ?? 0
+const current = sections[index] ?? sections[0]!
+const firstPath = (items: Parameters<typeof pagesOf>[0]) => {
+  const first = pagesOf(items)[0]
+  return first ? pageToPath(first) : "/"
+}
+const tabs = current.version.tabs.filter((tab) => tab.label)
+const versions = data.tree.versions.filter((version) => version.label)
+const tabPosition = current.version.tabs.indexOf(current.tab)
+const versionHref = (version: (typeof versions)[number]) =>
+  firstPath((version.tabs[tabPosition] ?? version.tabs[0]!).items)
+---
+
+{
+  (tabs.length > 1 || versions.length > 1) && (
+    <div class="hgdc-sections">
+      {versions.length > 1 && (
+        <label class="hgdc-version">
+          <span class="sr-only">Version de la documentation</span>
+          <select data-hgdc-version>
+            {versions.map((version) => (
+              <option value={versionHref(version)} selected={version === current.version}>
+                {version.label}
+                {version.isDefault ? " (actuelle)" : ""}
+              </option>
+            ))}
+          </select>
+        </label>
+      )}
+      {tabs.length > 1 && (
+        <nav aria-label="Sections de la documentation">
+          <ul class="hgdc-tabs">
+            {tabs.map((tab) => (
+              <li>
+                <a href={firstPath(tab.items)} aria-current={tab === current.tab ? "page" : undefined}>
+                  {tab.label}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </nav>
+      )}
+    </div>
+  )
+}
+<Default><slot /></Default>
+
+<script>
+  for (const select of document.querySelectorAll<HTMLSelectElement>("[data-hgdc-version]"))
+    select.addEventListener("change", () => window.location.assign(select.value))
+</script>

package/src/overrides/route-data.ts

@@ -0,0 +1,33 @@
+import { defineRouteMiddleware, type StarlightRouteData } from "@astrojs/starlight/route-data"
+import data from "virtual:hgdc-docs/config"
+
+type Entry = StarlightRouteData["sidebar"][number]
+type Link = Extract<Entry, { type: "link" }>
+
+const containsCurrent = (entry: Entry): boolean =>
+  entry.type === "link" ? entry.isCurrent : entry.entries.some(containsCurrent)
+
+const links = (entries: Array<Entry>): Array<Link> =>
+  entries.flatMap((entry) => (entry.type === "link" ? [entry] : links(entry.entries)))
+
+/**
+ * Plusieurs versions ou onglets : la sidebar de Starlight en contient une entrée par
+ * couple (version, onglet). On ne garde que celle de la page affichée, et la pagination
+ * précédent / suivant reste dans cette section.
+ */
+export const onRequest = defineRouteMiddleware((context) => {
+  const route = context.locals.starlightRoute
+  const sections = data.tree.versions.flatMap((version) => version.tabs)
+  if (sections.length > 1) {
+    const index = Math.max(route.sidebar.findIndex(containsCurrent), 0)
+    const section = route.sidebar[index]
+    if (section?.type === "group") route.sidebar = section.entries
+    context.locals.hgdcSection = index
+  }
+  const all = links(route.sidebar)
+  const current = all.findIndex((link) => link.isCurrent)
+  if (current !== -1 && route.pagination) {
+    route.pagination.prev = all[current - 1]
+    route.pagination.next = all[current + 1]
+  }
+})