@hgdc/docs 0.1.1 → 0.3.0

package/src/core/validate.ts

@@ -0,0 +1,276 @@
+import { compile } from "@mdx-js/mdx"
+import type { Root } from "mdast"
+import remarkGfm from "remark-gfm"
+import { parse as parseYaml } from "yaml"
+
+import { isMdxComponent } from "./components.ts"
+import { parseDocsConfig } from "./config.ts"
+import { missingPages, normalizeNavigation, pageToSlug } from "./navigation.ts"
+
+/**
+ * Ce que le build refuserait, vérifié avant de publier : l'éditeur de la console bloque
+ * la publication sur la moindre erreur, avec la ligne à corriger. Même compilateur MDX
+ * que le build (`@mdx-js/mdx`, GFM), même schéma de `docs.json`, même règle de pages.
+ */
+export type Problem = { file: string; line: number | null; column: number | null; message: string }
+
+/** Une page de la doc : `.mdx` ou `.md` à l'intérieur du dossier. */
+export const PAGE_FILE = /\.(mdx|md)$/i
+
+const IMAGE_FILE = /\.(png|jpe?g|gif|svg|webp|avif|ico)$/i
+
+/**
+ * Fichier que l'éditeur peut écrire, relatif au dossier de la doc : `docs.json`, pages et
+ * images. Jamais un dossier caché ni la configuration du build (même règle que Host,
+ * `isEditablePath` d'agenthost, qui revérifie).
+ */
+export function isDocFile(path: string): boolean {
+  if (path.length === 0 || path.length > 300) return false
+  if (path.startsWith("/") || path.endsWith("/") || path.includes("\\")) return false
+  const segments = path.split("/")
+  if (segments.some((s) => s === "" || s === "." || s === ".." || s.startsWith("."))) return false
+  if (segments.includes("node_modules") || segments[0] === "dist") return false
+  if (!/^[\p{L}\p{N} ._/()+@-]+$/u.test(path)) return false
+  return path === "docs.json" || PAGE_FILE.test(path) || IMAGE_FILE.test(path)
+}
+
+export function isImageFile(path: string): boolean {
+  return IMAGE_FILE.test(path)
+}
+
+/** Fichiers Markdown du dossier qui ne sont pas des pages (`template/src/content.config.ts`). */
+const NOT_PAGES = new Set(["README.md", "CHANGELOG.md"])
+
+/**
+ * Une page du site : `.mdx` ou `.md`, sauf un extrait (`_nom.mdx`, inclus par d'autres pages)
+ * et le README ou le CHANGELOG à la racine, que le build ignore.
+ */
+export function isPageFile(file: string): boolean {
+  return PAGE_FILE.test(file) && !NOT_PAGES.has(file) && !(file.split("/").at(-1) ?? "").startsWith("_")
+}
+
+/** `guides/publier.mdx` → `guides/publier` : le chemin de page de `docs.json` ; `null` pour un autre fichier. */
+export function pageOfFile(file: string): string | null {
+  return isPageFile(file) ? file.replace(PAGE_FILE, "") : null
+}
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n?---[ \t]*(?:\r?\n|$)/
+
+export type Frontmatter = { raw: string | null; body: string; lines: number }
+
+/** En-tête YAML d'une page et corps, avec le nombre de lignes de l'en-tête (pour garder les numéros de ligne). */
+export function splitFrontmatter(source: string): Frontmatter {
+  const match = FRONTMATTER.exec(source)
+  if (!match) return { raw: null, body: source, lines: 0 }
+  const header = match[0]
+  const lines = header.split("\n").length - (header.endsWith("\n") ? 1 : 0)
+  return { raw: match[1] ?? "", body: source.slice(header.length), lines }
+}
+
+/** Lit l'en-tête d'une page : objet YAML, ou `null` s'il manque ou ne se lit pas. */
+export function readFrontmatter(source: string): Record<string, unknown> | null {
+  const { raw } = splitFrontmatter(source)
+  if (raw === null) return null
+  try {
+    const data: unknown = parseYaml(raw)
+    return data && typeof data === "object" && !Array.isArray(data) ? (data as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}
+
+type Position = { start?: { line?: number; column?: number } }
+type MdxNode = { type: string; name?: string | null; position?: Position; children?: Array<MdxNode> }
+
+/** Composants appelés par la page sans exister : le build échouerait au rendu. */
+function unknownComponents(problems: Array<Problem>, file: string) {
+  return () => (tree: Root) => {
+    const declared = new Set<string>()
+    const walk = (node: MdxNode) => {
+      if (node.type === "mdxjsEsm") {
+        const value = (node as unknown as { value: string }).value
+        for (const match of value.matchAll(/import\s+(?:\{([^}]*)\}|([A-Za-z_$][\w$]*))/g)) {
+          for (const name of (match[1] ?? match[2] ?? "").split(","))
+            declared.add(
+              name
+                .split(/\s+as\s+/)
+                .pop()!
+                .trim(),
+            )
+        }
+        for (const match of value.matchAll(/export\s+(?:const|function)\s+([A-Za-z_$][\w$]*)/g)) declared.add(match[1]!)
+      }
+      for (const child of node.children ?? []) walk(child)
+    }
+    walk(tree as unknown as MdxNode)
+    const check = (node: MdxNode) => {
+      if ((node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && node.name) {
+        const root = node.name.split(".")[0]!
+        if (/^[A-Z]/.test(root) && !isMdxComponent(root) && !declared.has(root))
+          problems.push({
+            file,
+            line: node.position?.start?.line ?? null,
+            column: node.position?.start?.column ?? null,
+            message: `Le composant <${node.name}> n'existe pas. Composants disponibles : <Note>, <Tip>, <Card>, <Steps>…`,
+          })
+      }
+      for (const child of node.children ?? []) check(child)
+    }
+    check(tree as unknown as MdxNode)
+  }
+}
+
+const TRANSLATIONS: Array<[RegExp, (m: RegExpMatchArray) => string]> = [
+  [/Expected a closing tag for `<([^>]+)>`/, (m) => `La balise <${m[1]}> n'est jamais fermée.`],
+  [
+    /Unexpected closing slash `\/` in tag, expected an open tag first/,
+    () => "Balise fermante sans balise ouvrante correspondante.",
+  ],
+  [
+    /Unexpected closing tag `<\/([^>]+)>`, expected corresponding closing tag for `<([^>]+)>`/,
+    (m) => `</${m[1]}> ferme la mauvaise balise : <${m[2]}> est encore ouverte.`,
+  ],
+  [
+    /Expected the closing tag `<\/([^>]+)>` either after the end of/,
+    (m) =>
+      `</${m[1]}> est mal placée : ouvre et ferme <${m[1]}> sur leurs propres lignes, ou sur la même ligne que le texte.`,
+  ],
+  [
+    /Could not parse expression with acorn/,
+    () => "Expression entre accolades illisible : échappe « { » par « \\{ » si c'est du texte.",
+  ],
+  [/Could not parse import\/exports with acorn/, () => "Ligne import ou export illisible."],
+  [
+    /Unexpected end of file in expression, expected a corresponding closing brace for `\{`/,
+    () => "Accolade « { » jamais fermée : échappe-la par « \\{ » si c'est du texte.",
+  ],
+  [
+    /Unexpected character `(.)` \(U\+[0-9A-F]+\) before name/,
+    (m) => `Caractère « ${m[1]} » inattendu après « < » : écris « &lt; » pour un chevron dans le texte.`,
+  ],
+  [/Unexpected lazy line in/, () => "Ligne mal indentée à l'intérieur d'un bloc (citation, liste ou composant)."],
+]
+
+function translate(reason: string): string {
+  for (const [pattern, render] of TRANSLATIONS) {
+    const match = reason.match(pattern)
+    if (match) return render(match)
+  }
+  return `Syntaxe MDX invalide : ${reason}`
+}
+
+type Point = { line?: number; column?: number }
+type VFileMessageLike = {
+  reason?: string
+  message?: string
+  line?: number | null
+  column?: number | null
+  place?: (Point & { start?: Point }) | null
+}
+
+/** Position d'une erreur de MDX : son point, sinon celui cité dans le message (`(7:1-7:7)`). */
+function positionOf(failure: VFileMessageLike, reason: string): { line: number | null; column: number | null } {
+  const point = failure.place?.start ?? failure.place
+  if (failure.line) return { line: failure.line, column: failure.column ?? null }
+  if (point?.line) return { line: point.line, column: point.column ?? null }
+  const cited = reason.match(/\((\d+):(\d+)/)
+  return cited ? { line: Number(cited[1]), column: Number(cited[2]) } : { line: null, column: null }
+}
+
+/** En-tête lu ; `undefined` (et une erreur notée) s'il ne se lit pas. */
+function checkYaml(problems: Array<Problem>, file: string, raw: string): unknown {
+  try {
+    return parseYaml(raw)
+  } catch (error) {
+    const position = (error as { linePos?: Array<{ line: number; col: number }> }).linePos?.[0]
+    problems.push({
+      file,
+      line: position ? position.line + 1 : 1,
+      column: position?.col ?? null,
+      message: "En-tête illisible : vérifie les deux-points et les guillemets (YAML).",
+    })
+    return undefined
+  }
+}
+
+/**
+ * Vérifie une page : en-tête YAML avec un `title` (Starlight l'exige), compilation MDX
+ * comme au build, composants connus. Les numéros de ligne sont ceux du fichier entier.
+ */
+export async function checkPage(file: string, source: string): Promise<Array<Problem>> {
+  const problems: Array<Problem> = []
+  const front = splitFrontmatter(source)
+  // Un extrait ou le README n'est pas une page : seule la syntaxe compte, pas l'en-tête.
+  if (!isPageFile(file)) {
+    if (front.raw !== null) checkYaml(problems, file, front.raw)
+  } else if (front.raw === null) {
+    problems.push({
+      file,
+      line: 1,
+      column: 1,
+      message: "Il manque l'en-tête de la page : commence par ---, title: Le titre, puis ---.",
+    })
+  } else {
+    const data = checkYaml(problems, file, front.raw)
+    const title = data && typeof data === "object" ? (data as Record<string, unknown>).title : undefined
+    if (data !== undefined && (typeof title !== "string" || !title.trim()))
+      problems.push({
+        file,
+        line: 2,
+        column: 1,
+        message: "L'en-tête doit donner un titre : title: Le titre de la page.",
+      })
+  }
+
+  // Les lignes de l'en-tête restent, vides : les positions de MDX tombent sur la bonne ligne.
+  const body = "\n".repeat(front.lines) + front.body
+  try {
+    await compile(body, {
+      format: file.toLowerCase().endsWith(".md") ? "md" : "mdx",
+      remarkPlugins: [remarkGfm, unknownComponents(problems, file)],
+    })
+  } catch (error) {
+    const failure = error as VFileMessageLike
+    const reason = String(failure.reason ?? failure.message ?? error)
+    problems.push({ file, ...positionOf(failure, reason), message: translate(reason) })
+  }
+  return problems.sort((a, b) => (a.line ?? 0) - (b.line ?? 0))
+}
+
+/**
+ * Vérifie `docs.json` et sa navigation contre les fichiers de la doc : schéma, une seule
+ * forme de navigation, et chaque page citée présente dans le dossier.
+ */
+export function checkSite(docsJson: string, files: Iterable<string>): Array<Problem> {
+  const parsed = parseDocsConfig(docsJson)
+  if (!parsed.ok) return parsed.errors.map((message) => ({ file: "docs.json", line: null, column: null, message }))
+  const existing = new Set<string>()
+  for (const file of files) {
+    const page = pageOfFile(file)
+    if (page) existing.add(pageToSlug(page))
+  }
+  const problems: Array<Problem> = missingPages(normalizeNavigation(parsed.config), existing).map((page) => ({
+    file: "docs.json",
+    line: null,
+    column: null,
+    message: `La navigation cite la page ${page}, mais ${page}.mdx n'existe pas.`,
+  }))
+  const slug = (path: string) =>
+    path
+      .split(/[?#]/)[0]!
+      .replace(/^\/+|\/+$/g, "")
+      .toLowerCase()
+  const sources = new Set<string>()
+  for (const redirect of parsed.config.redirects ?? []) {
+    const source = slug(redirect.source)
+    const say = (message: string) => problems.push({ file: "docs.json", line: null, column: null, message })
+    if (sources.has(source)) say(`Deux redirections partent de ${redirect.source}.`)
+    sources.add(source)
+    // Une redirection depuis une page qui existe la cacherait : le build écrirait les deux au même endroit.
+    if (existing.has(source))
+      say(`La redirection ${redirect.source} masque une page qui existe : retire-la ou supprime la page.`)
+    if (redirect.destination.startsWith("/") && !existing.has(slug(redirect.destination)))
+      say(`La redirection ${redirect.source} mène à ${redirect.destination}, une page qui n'existe pas.`)
+  }
+  return problems
+}

package/src/integration.ts

@@ -1,4 +1,4 @@
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs"
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { dirname, join, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 
@@ -7,10 +7,18 @@ import starlight from "@astrojs/starlight"
 import type { AstroIntegration, AstroUserConfig } from "astro"
 
 import { remarkAutoImport } from "./build/auto-import.ts"
+import { remarkBaseLinks } from "./build/base-links.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 { parseDocsConfig, socialNetwork, withHostProject, type DocsConfig } from "./core/config.ts"
+import {
+  missingPages,
+  normalizeNavigation,
+  pageToSlug,
+  siteBase,
+  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`. */
@@ -35,12 +43,27 @@ export function readSiteOptions(env: NodeJS.ProcessEnv = process.env): SiteOptio
   return {
     contentDir,
     outDir: resolve(env.HGDC_DOCS_OUT ?? join(contentDir, "dist")),
-    site: env.HGDC_DOCS_SITE ?? vercelUrl,
+    site: siteOrigin(env.HGDC_DOCS_SITE ?? vercelUrl),
     apiEndpoint: env.HGDC_DOCS_API ?? DEFAULT_API,
     project: env.HGDC_DOCS_PROJECT ?? null,
   }
 }
 
+/**
+ * Origine du site seulement : le sous-chemin vient de `base` dans docs.json, pas de
+ * l'adresse (`https://app.ch/docs` et `https://app.ch` donnent le même site).
+ */
+function siteOrigin(value: string | null): string | null {
+  if (!value) return null
+  try {
+    return new URL(value).origin
+  } catch {
+    throw new DocsConfigError(
+      `HGDC_DOCS_SITE : adresse invalide (${value.slice(0, 100)}). Exemple : https://docs.exemple.ch`,
+    )
+  }
+}
+
 export class DocsConfigError extends Error {}
 
 export function loadDocsConfig(contentDir: string, hostProject: string | null = null): DocsConfig {
@@ -58,6 +81,8 @@ export type VirtualConfig = {
   tree: NavTree
   apiEndpoint: string
   site: string | null
+  /** Sous-chemin du site (`/docs`), `""` à la racine. */
+  base: string
 }
 
 const IGNORED_DIRS = new Set(["node_modules", "dist", ".hgdc-docs", ".git", ".github", ".vercel"])
@@ -123,17 +148,27 @@ export function starlightSidebar(
   )
 }
 
-const SOCIAL_ICONS = new Set([
-  "github",
-  "gitlab",
-  "linkedin",
-  "x.com",
-  "mastodon",
-  "discord",
-  "youtube",
-  "instagram",
-  "bluesky",
-])
+/**
+ * `redirects` de docs.json en redirections d'Astro : une page qui renvoie à la nouvelle
+ * adresse (le site est statique). Chemins écrits comme les liens de la doc, `base` ajouté.
+ */
+export function astroRedirects(
+  redirects: ReadonlyArray<{ source: string; destination: string; permanent?: boolean | undefined }>,
+  base: string,
+): Record<string, { status: 301 | 302; destination: string }> {
+  const slash = (path: string) => (path.endsWith("/") ? path : `${path}/`)
+  return Object.fromEntries(
+    redirects.map((item) => [
+      slash(item.source),
+      {
+        status: item.permanent === false ? 302 : 301,
+        destination: item.destination.startsWith("/")
+          ? `${base}${slash(item.destination.split("#")[0]!)}${item.destination.includes("#") ? `#${item.destination.split("#")[1]}` : ""}`
+          : item.destination,
+      },
+    ]),
+  )
+}
 
 function virtualConfigPlugin(data: VirtualConfig) {
   const id = "virtual:hgdc-docs/config"
@@ -144,6 +179,10 @@ function virtualConfigPlugin(data: VirtualConfig) {
   }
 }
 
+/** Site sous un sous-chemin : la racine renvoie vers la doc, pour une visite directe de l'hôte. */
+const rootRedirect = (base: string) =>
+  `<!doctype html><meta charset="utf-8"><meta name="robots" content="noindex"><meta http-equiv="refresh" content="0; url=${base}/"><link rel="canonical" href="${base}/"><a href="${base}/">Documentation</a>\n`
+
 function machineReadableOutputs(data: VirtualConfig, options: SiteOptions): AstroIntegration {
   return {
     name: "hgdc-docs-outputs",
@@ -155,12 +194,17 @@ function machineReadableOutputs(data: VirtualConfig, options: SiteOptions): Astr
           config: data.config,
           tree: data.tree,
           site: options.site,
+          base: data.base,
         })
         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.
+        // Sous un sous-chemin, le site va dans `dist/<base>/` : servi tel quel par Host, il
+        // répond aux mêmes adresses que derrière le proxy du produit (`/docs/_astro/…`).
         rmSync(options.outDir, { recursive: true, force: true })
-        cpSync(fileURLToPath(dir), options.outDir, { recursive: true, filter: (path) => !path.includes(".prerender") })
+        const target = join(options.outDir, ...data.base.split("/").filter(Boolean))
+        cpSync(fileURLToPath(dir), target, { recursive: true, filter: (path) => !path.includes(".prerender") })
+        if (data.base) writeFileSync(join(options.outDir, "index.html"), rootRedirect(data.base))
         logger.info(`Site écrit dans ${options.outDir}`)
       },
     },
@@ -176,13 +220,15 @@ export function createAstroConfig(options: SiteOptions = readSiteOptions()): Ast
     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 base = siteBase(config)
+  const data: VirtualConfig = { config, tree, apiEndpoint: options.apiEndpoint, site: options.site, base }
   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 }))
+  const social = Object.entries(config.footer?.socials ?? {}).flatMap(([key, href]) => {
+    const network = socialNetwork(key)
+    return network ? [{ icon: network.icon as "github", label: network.label, href }] : []
+  })
 
   return {
     root: file("../template"),
@@ -194,8 +240,10 @@ export function createAstroConfig(options: SiteOptions = readSiteOptions()): Ast
     outDir: file("../template/.build"),
     cacheDir: join(options.contentDir, ".hgdc-docs", "cache"),
     site: options.site ?? undefined,
+    ...(base ? { base } : {}),
     trailingSlash: "always",
-    markdown: { processor: unified({ remarkPlugins: [remarkAutoImport] }) },
+    redirects: astroRedirects(config.redirects ?? [], base),
+    markdown: { processor: unified({ remarkPlugins: [remarkAutoImport, [remarkBaseLinks, { base }]] }) },
     vite: {
       plugins: [virtualConfigPlugin(data)],
       server: { fs: { allow: [options.contentDir, file("..")] } },
@@ -219,6 +267,8 @@ export function createAstroConfig(options: SiteOptions = readSiteOptions()): Ast
           Sidebar: file("./overrides/Sidebar.astro"),
           PageTitle: file("./overrides/PageTitle.astro"),
           PageFrame: file("./overrides/PageFrame.astro"),
+          SocialIcons: file("./overrides/SocialIcons.astro"),
+          Footer: file("./overrides/Footer.astro"),
         },
         expressiveCode: { themes: ["github-dark-default", "github-light-default"] },
         pagination: true,

package/src/overrides/Footer.astro

@@ -0,0 +1,154 @@
+---
+import Default from "@astrojs/starlight/components/Footer.astro"
+import data from "virtual:hgdc-docs/config"
+
+// « Cette page t'a aidé ? » au bas de chaque page, envoyé à la console (`/api/v1/feedback`).
+// Sans projet relié, rien n'est affiché : il n'y a personne pour lire les réponses.
+const endpoint = new URL("/api/v1/feedback", data.config.assistant?.endpoint ?? data.apiEndpoint).toString()
+---
+
+{
+  data.config.project && (
+    <hgdc-feedback class="hgdc-feedback not-content" data-endpoint={endpoint} data-project={data.config.project} data-pagefind-ignore>
+      <div data-step="ask">
+        <p class="hgdc-feedback__question">Cette page t'a aidé ?</p>
+        <div class="hgdc-feedback__choices">
+          <button type="button" data-helpful="true">Oui</button>
+          <button type="button" data-helpful="false">Non</button>
+        </div>
+      </div>
+      <form data-step="comment" hidden>
+        <label for="hgdc-feedback-comment">Qu'est-ce qui manquait ou pourrait être plus clair ? (facultatif)</label>
+        <textarea id="hgdc-feedback-comment" name="comment" rows="3" maxlength="1000"></textarea>
+        <div class="hgdc-feedback__choices">
+          <button type="submit">Envoyer</button>
+          <button type="button" data-skip>Passer</button>
+        </div>
+      </form>
+      <p data-step="done" class="hgdc-feedback__done" role="status" hidden>Merci, c'est noté.</p>
+    </hgdc-feedback>
+  )
+}
+<Default />
+
+<script>
+  class HgdcFeedback extends HTMLElement {
+    #helpful: boolean | null = null
+
+    connectedCallback() {
+      for (const button of this.querySelectorAll<HTMLButtonElement>("[data-helpful]"))
+        button.addEventListener("click", () => this.#choose(button.dataset.helpful === "true"))
+      const form = this.querySelector("form")!
+      form.addEventListener("submit", (event) => {
+        event.preventDefault()
+        const comment = new FormData(form).get("comment")
+        void this.#send(typeof comment === "string" ? comment.trim() : "")
+      })
+      this.querySelector("[data-skip]")?.addEventListener("click", () => void this.#send(""))
+    }
+
+    #show(step: "ask" | "comment" | "done") {
+      for (const element of this.querySelectorAll<HTMLElement>("[data-step]")) element.hidden = element.dataset.step !== step
+      if (step === "comment") this.querySelector("textarea")?.focus()
+    }
+
+    #choose(helpful: boolean) {
+      this.#helpful = helpful
+      // Un oui part tout de suite ; un non attend le commentaire (ou « Passer ») : un seul envoi par avis.
+      if (helpful) void this.#send("")
+      else this.#show("comment")
+    }
+
+    async #send(comment: string) {
+      if (this.#helpful === null) return
+      try {
+        await fetch(this.dataset.endpoint!, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            project: this.dataset.project,
+            page: location.pathname,
+            helpful: this.#helpful,
+            ...(comment ? { comment } : {}),
+          }),
+          keepalive: true,
+        })
+      } catch {
+        // Un retour perdu ne gêne pas la lecture : rien à afficher.
+      }
+      this.#show("done")
+    }
+  }
+  customElements.define("hgdc-feedback", HgdcFeedback)
+</script>
+
+<style>
+  .hgdc-feedback {
+    display: block;
+    margin-block: 2.5rem 1.5rem;
+    padding: 1rem 1.25rem;
+    border-radius: 1rem;
+    background: var(--sl-color-gray-6);
+  }
+  .hgdc-feedback__question,
+  .hgdc-feedback label {
+    margin: 0 0 0.6rem;
+    font-size: var(--sl-text-sm);
+    font-weight: 500;
+    color: var(--sl-color-white);
+  }
+  .hgdc-feedback [data-step="ask"] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem;
+  }
+  .hgdc-feedback [data-step="ask"] .hgdc-feedback__question {
+    margin: 0;
+  }
+  .hgdc-feedback [hidden] {
+    display: none !important;
+  }
+  .hgdc-feedback__choices {
+    display: flex;
+    gap: 0.5rem;
+  }
+  .hgdc-feedback button {
+    border: 1px solid var(--sl-color-gray-5);
+    background: var(--sl-color-black);
+    color: var(--sl-color-white);
+    border-radius: 999px;
+    padding: 0.35rem 1rem;
+    font: inherit;
+    font-size: var(--sl-text-sm);
+    cursor: pointer;
+  }
+  .hgdc-feedback button:hover {
+    border-color: var(--sl-color-accent);
+  }
+  .hgdc-feedback button[type="submit"] {
+    background: var(--sl-color-accent);
+    border-color: var(--sl-color-accent);
+    color: var(--hgdc-on-accent, #fff);
+  }
+  .hgdc-feedback form {
+    display: grid;
+    gap: 0.6rem;
+  }
+  .hgdc-feedback textarea {
+    width: 100%;
+    border-radius: 0.75rem;
+    border: 1px solid var(--sl-color-gray-5);
+    background: var(--sl-color-black);
+    color: var(--sl-color-white);
+    padding: 0.5rem 0.75rem;
+    font: inherit;
+    font-size: var(--sl-text-sm);
+  }
+  .hgdc-feedback__done {
+    margin: 0;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-2);
+  }
+</style>

package/src/overrides/Head.astro

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

package/src/overrides/PageTitle.astro

@@ -3,8 +3,9 @@ import Default from "@astrojs/starlight/components/PageTitle.astro"
 import data from "virtual:hgdc-docs/config"
 
 import { markdownPath } from "../core/llms.ts"
+import { withBase, withoutBase } from "../core/navigation.ts"
 
-const markdown = markdownPath(Astro.url.pathname)
+const markdown = withBase(data.base, markdownPath(withoutBase(data.base, Astro.url.pathname)))
 const assistant = Boolean(data.config.project) && data.config.assistant?.enabled !== false
 ---
 
@@ -29,7 +30,7 @@ const assistant = Boolean(data.config.project) && data.config.assistant?.enabled
         <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>
+        <li><a href={withBase(data.base, "/llms.txt")}>Index pour les agents (llms.txt)</a></li>
       </ul>
     </details>
     {

package/src/overrides/Sidebar.astro

@@ -2,7 +2,7 @@
 import Default from "@astrojs/starlight/components/Sidebar.astro"
 import data from "virtual:hgdc-docs/config"
 
-import { pagesOf, pageToPath } from "../core/navigation.ts"
+import { pagesOf, pageToPath, withBase } 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.
@@ -11,7 +11,7 @@ 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) : "/"
+  return withBase(data.base, first ? pageToPath(first) : "/")
 }
 const tabs = current.version.tabs.filter((tab) => tab.label)
 const versions = data.tree.versions.filter((version) => version.label)