@hgdc/docs 0.1.1 → 0.3.0

package/docs.schema.json

@@ -23,6 +23,10 @@
       "type": "string",
       "enum": ["fr", "en", "de", "it"]
     },
+    "base": {
+      "type": "string",
+      "pattern": "^(?:\\/[a-z0-9][a-z0-9_-]*)+$"
+    },
     "colors": {
       "type": "object",
       "properties": {
@@ -244,6 +248,27 @@
         }
       }
     },
+    "redirects": {
+      "maxItems": 500,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "source": {
+            "type": "string",
+            "pattern": "^\\/(?!\\/)[A-Za-z0-9._~\\-/%]*$"
+          },
+          "destination": {
+            "type": "string",
+            "minLength": 1
+          },
+          "permanent": {
+            "type": "boolean"
+          }
+        },
+        "required": ["source", "destination"]
+      }
+    },
     "assistant": {
       "type": "object",
       "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hgdc/docs",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -31,6 +31,7 @@
     "@astrojs/starlight": "0.42.6",
     "@fontsource-variable/geist": "5.3.0",
     "@fontsource-variable/inter": "5.3.0",
+    "@mdx-js/mdx": "3.1.1",
     "astro": "7.3.8",
     "github-slugger": "2.0.0",
     "hast-util-select": "6.0.4",
@@ -41,6 +42,7 @@
     "remark-stringify": "11.0.0",
     "unified": "11.0.5",
     "vfile": "6.0.3",
+    "yaml": "2.9.1",
     "zod": "4.6.5"
   },
   "devDependencies": {

package/src/build/auto-import.ts

@@ -1,30 +1,7 @@
 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
+import { MDX_COMPONENTS } from "../core/components.ts"
 
 const SOURCE = "@hgdc/docs/components"
 
@@ -64,6 +41,10 @@ function importNode(name: string): EsmNode {
   }
 }
 
+/**
+ * Ajoute en tête de chaque page MDX l'import des composants (`core/components.ts`) que la
+ * page n'importe pas déjà elle-même : `<Note>`, `<Steps>`… s'écrivent sans `import`.
+ */
 export function remarkAutoImport() {
   return (tree: Root, file: VFile) => {
     if (!String(file.path ?? file.history.at(-1) ?? "").endsWith(".mdx")) return

package/src/build/base-links.ts

@@ -0,0 +1,35 @@
+import type { Root } from "mdast"
+
+import { withBase } from "../core/navigation.ts"
+
+type Node = { type: string; url?: unknown; attributes?: unknown; children?: Array<Node> }
+type Attribute = { type: string; name?: string; value?: unknown }
+
+/** Attributs JSX qui portent une adresse : `<Card href>`, `<img src>`, `<a href>`, `<video poster>`. */
+const URL_ATTRIBUTES = new Set(["href", "src", "poster"])
+
+/**
+ * Site servi sous un sous-chemin (`base: "/docs"`) : les liens et médias écrits depuis la
+ * racine du site (`/guides/publier/`, `/images/x.png`) reçoivent le sous-chemin, dans le
+ * Markdown (`[…](/…)`, `![…](/…)`, définitions) comme dans les composants MDX. Le rédacteur
+ * écrit ses liens comme pour un site à la racine ; la doc reste déplaçable.
+ */
+export function remarkBaseLinks(options: { base: string }) {
+  const { base } = options
+  return (tree: Root) => {
+    if (!base) return
+    const walk = (node: Node) => {
+      if (typeof node.url === "string") node.url = withBase(base, node.url)
+      // Les directives (`:::note{…}`) portent un objet d'attributs : seuls ceux de JSX nous intéressent.
+      for (const attribute of Array.isArray(node.attributes) ? (node.attributes as Array<Attribute>) : [])
+        if (
+          attribute.type === "mdxJsxAttribute" &&
+          URL_ATTRIBUTES.has(attribute.name ?? "") &&
+          typeof attribute.value === "string"
+        )
+          attribute.value = withBase(base, attribute.value)
+      for (const child of node.children ?? []) walk(child)
+    }
+    walk(tree as unknown as Node)
+  }
+}

package/src/build/outputs.ts

@@ -10,10 +10,18 @@ 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 { allPages, locatePage, pageToPath, withBase, 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 }
+type Input = {
+  outDir: string
+  pathnames: Array<string>
+  config: DocsConfig
+  tree: NavTree
+  site: string | null
+  /** Sous-chemin du site (`/docs`) : porté par les chemins publiés, pas par les fichiers écrits ici. */
+  base?: string
+}
 
 /** `guides/publier/` (pathname d'Astro) → `/guides/publier/`. */
 const normalize = (pathname: string) => `/${pathname}`.replace(/\/+/g, "/").replace(/([^/])$/, "$1/")
@@ -24,6 +32,7 @@ const normalize = (pathname: string) => `/${pathname}`.replace(/\/+/g, "/").repl
  * navigation y entrent : une page hors navigation n'est pas annoncée aux agents.
  */
 export async function writeMachineReadable(input: Input): Promise<{ pages: number }> {
+  const base = input.base ?? ""
   const byPath = new Map(allPages(input.tree).map((page) => [pageToPath(page), page]))
   const pages = new Map<string, LlmsPage>()
   const corpusPages: Corpus["pages"] = []
@@ -45,7 +54,7 @@ export async function writeMachineReadable(input: Input): Promise<{ pages: numbe
     pages.set(page, entry)
     await write(input.outDir, markdownPath(path), `# ${title}\n\n${markdown}\n`)
     corpusPages.push({
-      path,
+      path: withBase(base, path),
       title,
       description: entry.description,
       version: locatePage(input.tree, page)?.version.id ?? null,
@@ -57,6 +66,7 @@ export async function writeMachineReadable(input: Input): Promise<{ pages: numbe
     name: input.config.name,
     description: input.config.description ?? null,
     site: input.site,
+    base,
     tree: input.tree,
     pages,
   }
@@ -75,7 +85,7 @@ export async function writeMachineReadable(input: Input): Promise<{ pages: numbe
     builtAt: new Date().toISOString(),
     theme: {
       primary: input.config.colors?.primary ?? null,
-      logo: typeof logo === "string" ? logo : (logo?.light ?? null),
+      logo: withLogoBase(base, typeof logo === "string" ? logo : (logo?.light ?? null)),
     },
     versions: input.tree.versions.map(({ id, label, isDefault }) => ({ id, label, isDefault })),
     pages: corpusPages,
@@ -84,6 +94,9 @@ export async function writeMachineReadable(input: Input): Promise<{ pages: numbe
   return { pages: pages.size }
 }
 
+const withLogoBase = (base: string, logo: string | null) =>
+  logo ? withBase(base, logo.startsWith("/") || logo.includes("://") ? logo : `/${logo}`) : null
+
 async function write(outDir: string, path: string, content: string): Promise<void> {
   const target = join(outDir, path)
   await mkdir(dirname(target), { recursive: true })

package/src/core/components.ts

@@ -0,0 +1,166 @@
+/**
+ * Composants disponibles dans chaque page MDX sans `import`, comme chez Mintlify
+ * (`<Note>`, `<Steps>`, `<Card>`…). Lus par le build (`build/auto-import.ts`) et par
+ * l'éditeur de la console (validation, insertion par « / » ou « < », mode visuel).
+ * Les props décrites ici sont celles des fichiers `src/components/*.astro`.
+ */
+export const MDX_COMPONENTS = [
+  "Accordion",
+  "AccordionGroup",
+  "Card",
+  "CardGroup",
+  "Check",
+  "CodeGroup",
+  "Columns",
+  "Danger",
+  "Frame",
+  "Info",
+  "Note",
+  "Step",
+  "Steps",
+  "Tab",
+  "Tabs",
+  "Tip",
+  "Warning",
+] as const
+
+export type MdxComponent = (typeof MDX_COMPONENTS)[number]
+
+export function isMdxComponent(name: string): name is MdxComponent {
+  return (MDX_COMPONENTS as ReadonlyArray<string>).includes(name)
+}
+
+export type ComponentProp = {
+  name: string
+  label: string
+  type: "string" | "number" | "boolean"
+  required?: boolean
+}
+
+/** Props de chaque composant, pour les formulaires du mode visuel. */
+export const COMPONENT_PROPS: Record<MdxComponent, ReadonlyArray<ComponentProp>> = {
+  Accordion: [
+    { name: "title", label: "Titre", type: "string", required: true },
+    { name: "defaultOpen", label: "Ouvert au départ", type: "boolean" },
+  ],
+  AccordionGroup: [],
+  Card: [
+    { name: "title", label: "Titre", type: "string", required: true },
+    { name: "href", label: "Lien", type: "string" },
+  ],
+  CardGroup: [{ name: "cols", label: "Colonnes", type: "number" }],
+  Check: [{ name: "title", label: "Titre", type: "string" }],
+  CodeGroup: [],
+  Columns: [{ name: "cols", label: "Colonnes", type: "number" }],
+  Danger: [{ name: "title", label: "Titre", type: "string" }],
+  Frame: [{ name: "caption", label: "Légende", type: "string" }],
+  Info: [{ name: "title", label: "Titre", type: "string" }],
+  Note: [{ name: "title", label: "Titre", type: "string" }],
+  Step: [{ name: "title", label: "Titre", type: "string", required: true }],
+  Steps: [],
+  Tab: [{ name: "title", label: "Titre", type: "string", required: true }],
+  Tabs: [{ name: "syncKey", label: "Clé de synchronisation", type: "string" }],
+  Tip: [{ name: "title", label: "Titre", type: "string" }],
+  Warning: [{ name: "title", label: "Titre", type: "string" }],
+}
+
+export type BlockCategory = "Encadrés" | "Mise en page" | "Contenu"
+
+/**
+ * Blocs proposés à l'insertion, dans l'ordre du menu. `snippet` est le MDX inséré ; `$|`
+ * marque l'endroit où placer le curseur. Plusieurs blocs peuvent produire le même
+ * composant (colonnes à 2, 3 ou 4).
+ */
+export type Block = {
+  id: string
+  label: string
+  description: string
+  category: BlockCategory
+  keywords: ReadonlyArray<string>
+  snippet: string
+}
+
+const callout = (name: string, label: string, description: string, keywords: Array<string>): Block => ({
+  id: name.toLowerCase(),
+  label,
+  description,
+  category: "Encadrés",
+  keywords: [name.toLowerCase(), ...keywords],
+  snippet: `<${name}>\n$|\n</${name}>`,
+})
+
+const columns = (cols: number): Block => ({
+  id: `columns-${cols}`,
+  label: `${cols} colonnes`,
+  description: `Cartes côte à côte, sur ${cols} colonnes.`,
+  category: "Mise en page",
+  keywords: ["colonnes", "columns", "grille", String(cols)],
+  snippet: `<Columns cols={${cols}}>\n${Array.from({ length: cols }, (_, i) => `  <Card title="Carte ${i + 1}">${i === 0 ? "$|" : ""}</Card>`).join("\n")}\n</Columns>`,
+})
+
+export const BLOCKS: ReadonlyArray<Block> = [
+  callout("Note", "Note", "Une information utile à côté du texte.", ["information", "remarque"]),
+  callout("Tip", "Conseil", "Une astuce qui fait gagner du temps.", ["astuce", "conseil"]),
+  callout("Info", "Info", "Un contexte ou une précision.", ["information"]),
+  callout("Warning", "Attention", "Un point à ne pas manquer.", ["attention", "avertissement"]),
+  callout("Danger", "Danger", "Une action risquée ou irréversible.", ["danger", "risque"]),
+  callout("Check", "Validé", "Une étape réussie, un résultat attendu.", ["validé", "succès", "ok"]),
+  columns(2),
+  columns(3),
+  columns(4),
+  {
+    id: "steps",
+    label: "Étapes",
+    description: "Une marche à suivre numérotée.",
+    category: "Mise en page",
+    keywords: ["étapes", "steps", "procédure"],
+    snippet:
+      '<Steps>\n  <Step title="Première étape">\n    $|\n  </Step>\n  <Step title="Deuxième étape">\n  </Step>\n</Steps>',
+  },
+  {
+    id: "tabs",
+    label: "Onglets",
+    description: "Plusieurs variantes d'un même contenu.",
+    category: "Mise en page",
+    keywords: ["onglets", "tabs"],
+    snippet: '<Tabs>\n  <Tab title="Premier">\n    $|\n  </Tab>\n  <Tab title="Second">\n  </Tab>\n</Tabs>',
+  },
+  {
+    id: "accordion",
+    label: "Accordéon",
+    description: "Un détail replié, ouvert au clic.",
+    category: "Mise en page",
+    keywords: ["accordéon", "accordion", "replié", "faq"],
+    snippet: '<AccordionGroup>\n  <Accordion title="Question">\n    $|\n  </Accordion>\n</AccordionGroup>',
+  },
+  {
+    id: "card",
+    label: "Carte",
+    description: "Un lien mis en avant, avec un titre.",
+    category: "Contenu",
+    keywords: ["carte", "card", "lien"],
+    snippet: '<Card title="Titre" href="/">\n  $|\n</Card>',
+  },
+  {
+    id: "code-group",
+    label: "Groupe de code",
+    description: "Le même exemple en plusieurs langages.",
+    category: "Contenu",
+    keywords: ["code", "codegroup", "exemple"],
+    snippet: "<CodeGroup>\n\n```bash npm\n$|\n```\n\n```bash bun\n\n```\n\n</CodeGroup>",
+  },
+  {
+    id: "frame",
+    label: "Cadre",
+    description: "Une image ou une capture, avec sa légende.",
+    category: "Contenu",
+    keywords: ["cadre", "frame", "image", "capture"],
+    snippet: '<Frame caption="Légende">\n  ![Description de l\'image]($|)\n</Frame>',
+  },
+]
+
+/** Texte à insérer et position du curseur dans ce texte. */
+export function expandSnippet(snippet: string): { text: string; cursor: number } {
+  const cursor = snippet.indexOf("$|")
+  return cursor === -1 ? { text: snippet, cursor: snippet.length } : { text: snippet.replace("$|", ""), cursor }
+}

package/src/core/config.ts

@@ -16,6 +16,8 @@ const PAGE = /^(?!\/)(?!.*\.\.)[a-z0-9][a-z0-9/_-]*$/i
 const PROJECT_ID_PATTERN = /^[a-z0-9]{8,64}$/
 
 const hex = z.string().regex(HEX, "couleur attendue au format #rrggbb")
+/** Sous-chemin du site (`/docs`) : un ou plusieurs segments, sans « / » final. */
+const BASE = /^(?:\/[a-z0-9][a-z0-9_-]*)+$/i
 
 export type NavPageRef = string
 export type NavGroupInput = { group: string; pages: Array<NavPageRef | NavGroupInput>; expanded?: boolean }
@@ -54,6 +56,47 @@ const logo = z.union([
   z.object({ light: z.string(), dark: z.string().optional(), href: z.string().optional() }),
 ])
 
+/**
+ * Réseaux du pied de page : clé de `footer.socials` (celles de Mintlify), libellé, icône de
+ * Starlight. Lu par le build et par le formulaire des réglages de la console.
+ */
+export const SOCIAL_NETWORKS = {
+  linkedin: { label: "LinkedIn", icon: "linkedin" },
+  github: { label: "GitHub", icon: "github" },
+  gitlab: { label: "GitLab", icon: "gitlab" },
+  x: { label: "X", icon: "x.com" },
+  youtube: { label: "YouTube", icon: "youtube" },
+  instagram: { label: "Instagram", icon: "instagram" },
+  facebook: { label: "Facebook", icon: "facebook" },
+  discord: { label: "Discord", icon: "discord" },
+  mastodon: { label: "Mastodon", icon: "mastodon" },
+  bluesky: { label: "Bluesky", icon: "blueSky" },
+  website: { label: "Site web", icon: "external" },
+} as const
+
+/** Ancienne écriture acceptée : `x.com` (Starlight) et `twitter` désignent X. */
+const SOCIAL_ALIASES: Record<string, keyof typeof SOCIAL_NETWORKS> = { "x.com": "x", twitter: "x" }
+
+export function socialNetwork(key: string): (typeof SOCIAL_NETWORKS)[keyof typeof SOCIAL_NETWORKS] | null {
+  const name = (SOCIAL_ALIASES[key] ?? key) as keyof typeof SOCIAL_NETWORKS
+  return SOCIAL_NETWORKS[name] ?? null
+}
+
+const REDIRECT_SOURCE = /^\/(?!\/)[A-Za-z0-9._~\-/%]*$/
+
+/** Ancienne adresse vers la nouvelle (champ `redirects` de Mintlify), sans motif. */
+const redirect = z.object({
+  source: z.string().regex(REDIRECT_SOURCE, "adresse source attendue, commençant par « / » (ex. /guides/ancien)"),
+  destination: z
+    .string()
+    .min(1)
+    .refine(
+      (value) => /^\/(?!\/)/.test(value) || value.startsWith("https://"),
+      "destination attendue : un chemin du site (« /… ») ou une adresse https://",
+    ),
+  permanent: z.boolean().optional(),
+})
+
 export const docsConfigSchema = z.object({
   $schema: z.string().optional(),
   name: z.string().min(1).max(80),
@@ -64,6 +107,12 @@ export const docsConfigSchema = z.object({
     .regex(PROJECT_ID_PATTERN, "identifiant de projet attendu, copié depuis la console docs.hgdc.ch")
     .optional(),
   language: z.enum(["fr", "en", "de", "it"]).default("fr"),
+  /**
+   * Sous-chemin où la doc est servie, quand un produit la publie derrière un proxy
+   * (`https://app.exemple.ch/docs`). Liens, médias, recherche, `llms.txt` et pages `.md`
+   * le portent ; le site est écrit dans `dist/<base>/`.
+   */
+  base: z.string().regex(BASE, "sous-chemin attendu, sans « / » final (ex. /docs)").optional(),
   colors: z.object({ primary: hex, light: hex.optional(), dark: hex.optional() }).optional(),
   logo: logo.optional(),
   favicon: z.string().optional(),
@@ -78,6 +127,7 @@ export const docsConfigSchema = z.object({
     })
     .optional(),
   footer: z.object({ socials: z.record(z.string(), z.url()).optional() }).optional(),
+  redirects: z.array(redirect).max(500, "500 redirections au plus").optional(),
   assistant: z
     .object({
       enabled: z.boolean().default(true),

package/src/core/feedback-api.ts

@@ -0,0 +1,17 @@
+import { z } from "zod"
+
+/**
+ * Contrat de `POST /api/v1/feedback` entre le bas de chaque page (« Cette page t'a aidé ? »)
+ * et la console. Aucune donnée personnelle : la page, la réponse, un commentaire facultatif.
+ */
+export const MAX_FEEDBACK_COMMENT = 1000
+
+export const feedbackRequestSchema = z.object({
+  project: z.string().regex(/^[a-z0-9]{8,64}$/),
+  /** Chemin de la page, `base` compris (`/docs/guides/publier/`). */
+  page: z.string().startsWith("/").max(512),
+  helpful: z.boolean(),
+  comment: z.string().trim().max(MAX_FEEDBACK_COMMENT).optional(),
+})
+
+export type FeedbackRequest = z.infer<typeof feedbackRequestSchema>

package/src/core/llms.ts

@@ -1,5 +1,5 @@
 import type { NavItem, NavTree } from "./navigation.ts"
-import { pagesOf as pagesIn, pageToPath } from "./navigation.ts"
+import { pagesOf as pagesIn, pageToPath, withBase } from "./navigation.ts"
 
 /**
  * `llms.txt` et `llms-full.txt` au format de llmstxt.org : un H1, un résumé en citation,
@@ -12,6 +12,8 @@ export type LlmsInput = {
   name: string
   description: string | null
   site: string | null
+  /** Sous-chemin du site (`/docs`), `""` ou absent à la racine. */
+  base?: string
   tree: NavTree
   pages: ReadonlyMap<string, LlmsPage>
 }
@@ -22,14 +24,15 @@ export function markdownPath(path: string): string {
   return trimmed ? `${trimmed}.md` : "/index.md"
 }
 
-function url(site: string | null, path: string): string {
-  return site ? new URL(path, site).toString() : path
+function url(input: Pick<LlmsInput, "site" | "base">, path: string): string {
+  const full = withBase(input.base ?? "", path)
+  return input.site ? new URL(full, input.site).toString() : full
 }
 
 function link(input: LlmsInput, page: string): string | null {
   const data = input.pages.get(page)
   if (!data) return null
-  const target = url(input.site, markdownPath(pageToPath(page)))
+  const target = url(input, markdownPath(pageToPath(page)))
   return `- [${data.title}](${target})${data.description ? `: ${data.description}` : ""}`
 }
 
@@ -89,7 +92,7 @@ export function llmsFullTxt(input: LlmsInput, order: Array<string>): string {
   for (const page of order) {
     const data = input.pages.get(page)
     if (!data) continue
-    parts.push(`\n---\n\nSource : ${url(input.site, pageToPath(page))}\n\n# ${data.title}\n\n${data.markdown.trim()}`)
+    parts.push(`\n---\n\nSource : ${url(input, pageToPath(page))}\n\n# ${data.title}\n\n${data.markdown.trim()}`)
   }
   return `${parts.join("\n").trim()}\n`
 }

package/src/core/navigation.ts

@@ -82,6 +82,30 @@ export function pageToPath(page: string): string {
   return slug ? `/${slug}/` : "/"
 }
 
+/** Sous-chemin du site tel que docs.json le déclare, ou `""` pour un site à la racine. */
+export function siteBase(config: Pick<DocsConfig, "base">): string {
+  return config.base ? config.base.replace(/\/+$/, "") : ""
+}
+
+/**
+ * Chemin public d'un chemin du site : `/guides/publier/` → `/docs/guides/publier/` sous
+ * `base: "/docs"`. Un chemin qui porte déjà le sous-chemin, ou qui n'est pas absolu
+ * (`#ancre`, `https://…`, `//hôte`), reste tel quel.
+ */
+export function withBase(base: string, path: string): string {
+  if (!base || !path.startsWith("/") || path.startsWith("//")) return path
+  if (path === base || path.startsWith(`${base}/`) || path.startsWith(`${base}#`) || path.startsWith(`${base}?`))
+    return path
+  return `${base}${path}`
+}
+
+/** Chemin du site sans son sous-chemin : `/docs/guides/` → `/guides/`, `/docs/` → `/`. */
+export function withoutBase(base: string, pathname: string): string {
+  if (!base) return pathname
+  if (pathname === base) return "/"
+  return pathname.startsWith(`${base}/`) ? pathname.slice(base.length) : pathname
+}
+
 /** Pages citées dans la navigation mais absentes du dossier : erreur de build lisible. */
 export function missingPages(tree: NavTree, existing: ReadonlySet<string>): Array<string> {
   return [...new Set(allPages(tree))].filter((page) => !existing.has(pageToSlug(page)))