@hgdc/docs 0.0.0-stage → 0.1.0

package/bin/hgdc-docs.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// @ts-check
+// CLI de HGDC Docs : construit la doc du dossier courant (docs.json + pages MDX) avec le
+// modèle Starlight du paquet. En JavaScript : Node ne retire pas les types d'un fichier
+// situé dans node_modules, et ce fichier y vit chez le client.
+import { resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import { parseArgs } from "node:util"
+
+const USAGE = `Utilisation : hgdc-docs <dev|build|preview> [dossier] [--port 4321] [--host 0.0.0.0]
+
+  dev       site local, rechargé à chaque modification
+  build     site statique dans <dossier>/dist (llms.txt et corpus de l'assistant compris)
+  preview   sert le dernier build
+
+Variables : HGDC_DOCS_SITE (adresse publique), HGDC_DOCS_API (API de l'assistant), HGDC_DOCS_OUT.`
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  options: { port: { type: "string" }, host: { type: "string" }, help: { type: "boolean", short: "h" } },
+})
+const [command = "build", dir = "."] = positionals
+if (values.help || !["dev", "build", "preview"].includes(command)) {
+  process.stdout.write(`${USAGE}
+`)
+  process.exit(values.help ? 0 : 1)
+}
+
+process.env.HGDC_DOCS_DIR = resolve(dir)
+if (!process.env.HGDC_DOCS_OUT) process.env.HGDC_DOCS_OUT = resolve(dir, "dist")
+const root = fileURLToPath(new URL("../template/", import.meta.url))
+const port = values.port ? Number(values.port) : undefined
+const server = { ...(port ? { port } : {}), ...(values.host ? { host: values.host } : {}) }
+const inline = { root, server }
+
+// Astro écrit son cache dans le dossier courant : celui du modèle, pas le dépôt du client.
+process.chdir(root)
+const astro = await import("astro")
+try {
+  if (command === "build") await astro.build(inline)
+  else if (command === "dev") await astro.dev(inline)
+  else await astro.preview(inline)
+} catch (error) {
+  // Une erreur de docs.json se lit sans pile d'appels : elle dit déjà quoi corriger.
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(message.includes("docs.json") ? `\n${message}\n` : error)
+  process.exit(1)
+}

package/docs.schema.json

@@ -0,0 +1,294 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 300
+    },
+    "project": {
+      "type": "string",
+      "pattern": "^[a-z0-9]{8,64}$"
+    },
+    "language": {
+      "default": "fr",
+      "type": "string",
+      "enum": ["fr", "en", "de", "it"]
+    },
+    "colors": {
+      "type": "object",
+      "properties": {
+        "primary": {
+          "type": "string",
+          "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$"
+        },
+        "light": {
+          "type": "string",
+          "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$"
+        },
+        "dark": {
+          "type": "string",
+          "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$"
+        }
+      },
+      "required": ["primary"]
+    },
+    "logo": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "light": {
+              "type": "string"
+            },
+            "dark": {
+              "type": "string"
+            },
+            "href": {
+              "type": "string"
+            }
+          },
+          "required": ["light"]
+        }
+      ]
+    },
+    "favicon": {
+      "type": "string"
+    },
+    "navigation": {
+      "type": "object",
+      "properties": {
+        "versions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "version": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 32
+              },
+              "default": {
+                "type": "boolean"
+              },
+              "tabs": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "tab": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "groups": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/$defs/__schema0"
+                      }
+                    },
+                    "pages": {
+                      "type": "array",
+                      "items": {
+                        "anyOf": [
+                          {
+                            "type": "string",
+                            "pattern": "^(?!\\/)(?!.*\\.\\.)[a-z0-9][a-z0-9/_-]*$"
+                          },
+                          {
+                            "$ref": "#/$defs/__schema0"
+                          }
+                        ]
+                      }
+                    }
+                  },
+                  "required": ["tab"]
+                }
+              },
+              "groups": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/__schema0"
+                }
+              },
+              "pages": {
+                "type": "array",
+                "items": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "pattern": "^(?!\\/)(?!.*\\.\\.)[a-z0-9][a-z0-9/_-]*$"
+                    },
+                    {
+                      "$ref": "#/$defs/__schema0"
+                    }
+                  ]
+                }
+              }
+            },
+            "required": ["version"]
+          }
+        },
+        "tabs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "tab": {
+                "type": "string",
+                "minLength": 1
+              },
+              "groups": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/__schema0"
+                }
+              },
+              "pages": {
+                "type": "array",
+                "items": {
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "pattern": "^(?!\\/)(?!.*\\.\\.)[a-z0-9][a-z0-9/_-]*$"
+                    },
+                    {
+                      "$ref": "#/$defs/__schema0"
+                    }
+                  ]
+                }
+              }
+            },
+            "required": ["tab"]
+          }
+        },
+        "groups": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/__schema0"
+          }
+        },
+        "pages": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^(?!\\/)(?!.*\\.\\.)[a-z0-9][a-z0-9/_-]*$"
+              },
+              {
+                "$ref": "#/$defs/__schema0"
+              }
+            ]
+          }
+        }
+      }
+    },
+    "navbar": {
+      "type": "object",
+      "properties": {
+        "links": {
+          "maxItems": 5,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": {
+                "type": "string"
+              },
+              "href": {
+                "type": "string",
+                "format": "uri"
+              }
+            },
+            "required": ["label", "href"]
+          }
+        },
+        "primary": {
+          "type": "object",
+          "properties": {
+            "label": {
+              "type": "string"
+            },
+            "href": {
+              "type": "string",
+              "format": "uri"
+            }
+          },
+          "required": ["label", "href"]
+        }
+      }
+    },
+    "footer": {
+      "type": "object",
+      "properties": {
+        "socials": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "format": "uri"
+          }
+        }
+      }
+    },
+    "assistant": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": true,
+          "type": "boolean"
+        },
+        "endpoint": {
+          "type": "string",
+          "format": "uri"
+        }
+      }
+    }
+  },
+  "required": ["name", "navigation"],
+  "$defs": {
+    "__schema0": {
+      "type": "object",
+      "properties": {
+        "group": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pages": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^(?!\\/)(?!.*\\.\\.)[a-z0-9][a-z0-9/_-]*$"
+              },
+              {
+                "$ref": "#/$defs/__schema0"
+              }
+            ]
+          }
+        },
+        "expanded": {
+          "type": "boolean"
+        }
+      },
+      "required": ["group", "pages"]
+    }
+  },
+  "$id": "https://docs.hgdc.ch/docs.schema.json",
+  "title": "docs.json de HGDC Docs"
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@hgdc/docs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Modèle de site de HGDC Docs : documentation MDX (docs.json) construite avec Astro Starlight, recherche, versions, llms.txt et assistant.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "hgdc-docs": "./bin/hgdc-docs.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "docs.schema.json"
+  ],
+  "exports": {
+    "./core/*": "./src/core/*.ts",
+    "./integration": "./src/integration.ts",
+    "./components/*": "./src/components/*",
+    "./docs.schema.json": "./docs.schema.json",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "7.3.2",
+    "@astrojs/mdx": "8.0.3",
+    "@astrojs/starlight": "0.42.6",
+    "@fontsource-variable/geist": "5.3.0",
+    "@fontsource-variable/inter": "5.3.0",
+    "astro": "7.3.8",
+    "github-slugger": "2.0.0",
+    "hast-util-select": "6.0.4",
+    "hast-util-to-string": "3.0.1",
+    "rehype-parse": "9.0.1",
+    "rehype-remark": "10.0.1",
+    "remark-gfm": "4.0.1",
+    "remark-stringify": "11.0.0",
+    "unified": "11.0.5",
+    "vfile": "6.0.3",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3",
+    "@types/hast": "3.0.4",
+    "@types/mdast": "4.0.4"
+  }
+}

package/src/build/auto-import.ts

@@ -0,0 +1,74 @@
+import type { Root } from "mdast"
+import type { VFile } from "vfile"
+
+/**
+ * Composants disponibles dans chaque page MDX sans `import`, comme chez Mintlify
+ * (`<Note>`, `<Steps>`, `<Card>`…). Le plugin ajoute en tête du fichier l'import des
+ * composants que la page n'importe pas déjà elle-même.
+ */
+export const MDX_COMPONENTS = [
+  "Accordion",
+  "AccordionGroup",
+  "Card",
+  "CardGroup",
+  "Check",
+  "CodeGroup",
+  "Columns",
+  "Danger",
+  "Frame",
+  "Info",
+  "Note",
+  "Step",
+  "Steps",
+  "Tab",
+  "Tabs",
+  "Tip",
+  "Warning",
+] as const
+
+const SOURCE = "@hgdc/docs/components"
+
+type EsmNode = { type: "mdxjsEsm"; value: string; data?: { estree?: { body?: Array<EstreeImport> } } }
+type EstreeImport = { type: string; specifiers?: Array<{ local?: { name?: string } }> }
+
+function declaredNames(tree: Root): Set<string> {
+  const names = new Set<string>()
+  for (const node of tree.children as unknown as Array<EsmNode>) {
+    if (node.type !== "mdxjsEsm") continue
+    for (const statement of node.data?.estree?.body ?? [])
+      for (const specifier of statement.specifiers ?? []) if (specifier.local?.name) names.add(specifier.local.name)
+  }
+  return names
+}
+
+/** Import par défaut d'un fichier `.astro`, sous la forme ESTree qu'attend le compilateur MDX. */
+function importNode(name: string): EsmNode {
+  const source = `${SOURCE}/${name}.astro`
+  const identifier = { type: "Identifier", name }
+  return {
+    type: "mdxjsEsm",
+    value: `import ${name} from ${JSON.stringify(source)}`,
+    data: {
+      estree: {
+        type: "Program",
+        sourceType: "module",
+        body: [
+          {
+            type: "ImportDeclaration",
+            specifiers: [{ type: "ImportDefaultSpecifier", local: identifier }],
+            source: { type: "Literal", value: source, raw: JSON.stringify(source) },
+          },
+        ],
+      } as never,
+    },
+  }
+}
+
+export function remarkAutoImport() {
+  return (tree: Root, file: VFile) => {
+    if (!String(file.path ?? file.history.at(-1) ?? "").endsWith(".mdx")) return
+    const declared = declaredNames(tree)
+    const imports = MDX_COMPONENTS.filter((name) => !declared.has(name)).map(importNode)
+    tree.children.unshift(...(imports as never[]))
+  }
+}

package/src/build/markdown.ts

@@ -0,0 +1,114 @@
+import type { Element, Root } from "hast"
+import { select, selectAll } from "hast-util-select"
+import { toString } from "hast-util-to-string"
+import rehypeParse from "rehype-parse"
+import rehypeRemark from "rehype-remark"
+import remarkGfm from "remark-gfm"
+import remarkStringify from "remark-stringify"
+import { unified } from "unified"
+
+/**
+ * Page construite (HTML) → Markdown propre, pour `.md`, `llms-full.txt` et le corpus.
+ *
+ * On part du HTML final plutôt que du MDX source : les composants (encadrés, onglets,
+ * étapes) sont déjà rendus, et ce que lit l'agent est exactement ce que voit le visiteur.
+ */
+const REMOVED = [
+  "script",
+  "style",
+  "template",
+  "button",
+  ".sl-anchor-link",
+  "[data-hgdc-skip]",
+  ".expressive-code .copy",
+  "starlight-tabs [role=tablist]",
+]
+
+export function htmlToMarkdown(html: string): string {
+  const tree = unified().use(rehypeParse).parse(html) as Root
+  const content = select(".sl-markdown-content", tree) ?? select("main", tree)
+  if (!content) return ""
+  replaceCodeBlocks(content)
+  replaceAsides(content)
+  for (const selector of REMOVED) for (const node of selectAll(selector, content)) remove(content, node)
+
+  const root: Root = { type: "root", children: content.children }
+  const mdast = unified().use(rehypeRemark).runSync(root)
+  const markdown = unified()
+    .use(remarkGfm)
+    .use(remarkStringify, { bullet: "-", fences: true, rule: "-" })
+    .stringify(mdast)
+  return String(markdown)
+    .replace(/\n{3,}/g, "\n\n")
+    .trim()
+}
+
+/**
+ * Expressive Code découpe le code en une ligne par élément ; le texte exact, sauts de ligne
+ * compris, est dans `data-code` du bouton Copier (saut de ligne codé U+007F).
+ */
+function replaceCodeBlocks(content: Element): void {
+  for (const figure of selectAll(".expressive-code", content)) {
+    const code = select("[data-code]", figure)?.properties["dataCode"]
+    const language = select("pre[data-language]", figure)?.properties["dataLanguage"]
+    if (typeof code !== "string") continue
+    const pre: Element = {
+      type: "element",
+      tagName: "pre",
+      properties: {},
+      children: [
+        {
+          type: "element",
+          tagName: "code",
+          properties:
+            typeof language === "string" && language !== "plaintext" ? { className: [`language-${language}`] } : {},
+          children: [{ type: "text", value: code.replaceAll("\u007f", "\n") }],
+        },
+      ],
+    }
+    Object.assign(figure, pre)
+  }
+}
+
+/** Encadré → citation dont la première ligne porte le titre en gras : `> **Note**`. */
+function replaceAsides(content: Element): void {
+  for (const aside of selectAll("aside.starlight-aside", content)) {
+    const title = select(".starlight-aside__title", aside)
+    const body = select(".starlight-aside__content", aside)
+    const label = title ? toString(title as Parameters<typeof toString>[0]).trim() : ""
+    const quote: Element = {
+      type: "element",
+      tagName: "blockquote",
+      properties: {},
+      children: [
+        ...(label
+          ? [
+              {
+                type: "element" as const,
+                tagName: "p",
+                properties: {},
+                children: [
+                  {
+                    type: "element" as const,
+                    tagName: "strong",
+                    properties: {},
+                    children: [{ type: "text" as const, value: label }],
+                  },
+                ],
+              },
+            ]
+          : []),
+        ...(body?.children ?? []),
+      ],
+    }
+    Object.assign(aside, quote)
+  }
+  for (const title of selectAll(".hgdc-step__title", content)) {
+    title.children = [{ type: "element", tagName: "strong", properties: {}, children: [...title.children] }]
+  }
+}
+
+function remove(parent: Element | Root, target: Element): void {
+  parent.children = parent.children.filter((child) => child !== target)
+  for (const child of parent.children) if (child.type === "element") remove(child, target)
+}

package/src/build/outputs.ts

@@ -0,0 +1,91 @@
+import { existsSync } from "node:fs"
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+
+import { select } from "hast-util-select"
+import { toString } from "hast-util-to-string"
+import rehypeParse from "rehype-parse"
+import { unified } from "unified"
+
+import type { DocsConfig } from "../core/config.ts"
+import { CORPUS_FORMAT, CORPUS_PATH, MAX_PAGE_CHARS, type Corpus } from "../core/corpus.ts"
+import { llmsFullTxt, llmsTxt, markdownPath, type LlmsPage } from "../core/llms.ts"
+import { allPages, locatePage, pageToPath, type NavTree } from "../core/navigation.ts"
+import { htmlToMarkdown } from "./markdown.ts"
+
+type Input = { outDir: string; pathnames: Array<string>; config: DocsConfig; tree: NavTree; site: string | null }
+
+/** `guides/publier/` (pathname d'Astro) → `/guides/publier/`. */
+const normalize = (pathname: string) => `/${pathname}`.replace(/\/+/g, "/").replace(/([^/])$/, "$1/")
+
+/**
+ * Après le build : une version Markdown de chaque page, `llms.txt`, `llms-full.txt`
+ * (aussi sous `/.well-known/`) et le corpus de l'assistant. Seules les pages de la
+ * navigation y entrent : une page hors navigation n'est pas annoncée aux agents.
+ */
+export async function writeMachineReadable(input: Input): Promise<{ pages: number }> {
+  const byPath = new Map(allPages(input.tree).map((page) => [pageToPath(page), page]))
+  const pages = new Map<string, LlmsPage>()
+  const corpusPages: Corpus["pages"] = []
+
+  for (const pathname of input.pathnames) {
+    const path = normalize(pathname)
+    const page = byPath.get(path)
+    const htmlFile = join(input.outDir, path, "index.html")
+    if (!page || !existsSync(htmlFile)) continue
+    const html = await readFile(htmlFile, "utf8")
+    const tree = unified().use(rehypeParse).parse(html)
+    const heading = select("h1#_top", tree) ?? select("title", tree)
+    const title = heading ? toString(heading as Parameters<typeof toString>[0]).trim() : path
+    const description = select('meta[name="description"]', tree)?.properties["content"]
+    const markdown = htmlToMarkdown(html).slice(0, MAX_PAGE_CHARS)
+    // Starlight reprend la description du site quand la page n'en a pas : ce n'est pas la sienne.
+    const own = typeof description === "string" && description !== input.config.description ? description : null
+    const entry = { page, title, description: own, markdown }
+    pages.set(page, entry)
+    await write(input.outDir, markdownPath(path), `# ${title}\n\n${markdown}\n`)
+    corpusPages.push({
+      path,
+      title,
+      description: entry.description,
+      version: locatePage(input.tree, page)?.version.id ?? null,
+      markdown,
+    })
+  }
+
+  const llms = {
+    name: input.config.name,
+    description: input.config.description ?? null,
+    site: input.site,
+    tree: input.tree,
+    pages,
+  }
+  const index = llmsTxt(llms)
+  const full = llmsFullTxt(llms, [...new Set(allPages(input.tree))])
+  await write(input.outDir, "/llms.txt", index)
+  await write(input.outDir, "/.well-known/llms.txt", index)
+  await write(input.outDir, "/llms-full.txt", full)
+
+  const logo = input.config.logo
+  const corpus: Corpus = {
+    format: CORPUS_FORMAT,
+    project: input.config.project ?? null,
+    name: input.config.name,
+    language: input.config.language,
+    builtAt: new Date().toISOString(),
+    theme: {
+      primary: input.config.colors?.primary ?? null,
+      logo: typeof logo === "string" ? logo : (logo?.light ?? null),
+    },
+    versions: input.tree.versions.map(({ id, label, isDefault }) => ({ id, label, isDefault })),
+    pages: corpusPages,
+  }
+  await write(input.outDir, CORPUS_PATH, JSON.stringify(corpus))
+  return { pages: pages.size }
+}
+
+async function write(outDir: string, path: string, content: string): Promise<void> {
+  const target = join(outDir, path)
+  await mkdir(dirname(target), { recursive: true })
+  await writeFile(target, content)
+}