---
title: "Référence d'API — @nodefony/documentation"
source: docs/api/documentation.md
url: https://nodefony.github.io/nodefony-core/docs/api/documentation/
---


[Documentation](../../) › [Référence d'API](../) › `@nodefony/documentation`

> Générée depuis les déclarations de types publiées de `@nodefony/documentation` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

## `@nodefony/documentation`

`import { … } from "@nodefony/documentation"` — 39 symboles.

### Classes (6)

#### `DocNotFoundError`

```ts
class DocNotFoundError extends DocumentationError
```

Slug demandé absent de l'allowlist construite par le scan (404 logique).

- `constructor(slug: string)`

#### `DocUnsafeSlugError`

```ts
class DocUnsafeSlugError extends DocumentationError
```

Slug rejeté car potentiellement dangereux (traversée de répertoire, segment `..`, caractère hors charset). Sécurité : on ne touche JAMAIS au FS avec un tel slug.

- `constructor(slug: string)`

#### `DocumentationController`

```ts
class DocumentationController extends Controller
```

Data plane HTTP de la documentation Nodefony.

- `constructor(context: Context)`
- `tree(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>` — Index transverse : sections → pages, taguées par audience.
- `search(q?: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>` — Cherche dans le corpus — titres ET corps — et rend des extraits situés.
- `page(slug: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>` — Contenu d'une page + variables `{{ }}` résolues côté serveur.

#### `DocumentationError`

```ts
class DocumentationError extends nodefonyError
```

Erreur typée du module `@nodefony/documentation`.

- `readonly docCode: string` — Code machine stable (ex.
- `constructor(message: string, docCode?: string)`

#### `DocumentationService`

```ts
class DocumentationService extends Service
```

Service de documentation Nodefony — **headless** : produit l'index transverse et le contenu résolu des pages, sans rendre aucun HTML (le front Studio, un générateur statique ou le RAG le consomment).

- `module: Module`
- `constructor(module: Module)`
- `log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu` — Émet une entrée de log structurée — point d'entrée central pour TOUT log Nodefony.
- `registerVar(name: string, provider: DocVarProvider): void`
- `invalidate(): void`
- `getTree(): Promise<IDocTree>`
- `search(query: string, limit?: number): Promise<IDocSearchResult>` — Cherche `query` dans le corpus — titres ET corps — et rend des EXTRAITS.
- `getPage(slug: string): Promise<IDocPage>`

#### `default`

```ts
class Documentation extends Module<IDocumentationConfig>
```

- `static critical: boolean` — Module optionnel : un échec de son boot ne tue jamais le process (résilience Ph.3).
- `constructor(kernel: Kernel)`
- `configSchema(): unknown` — JSON Schema de la config documentation → data plane admin (config riche Studio).
- `onKernelRegister(): Promise<this>` — Phase `onRegister` : valide la config (défauts + override `module-documentation` + env) via `defineDocumentationConfig`, puis la ré-assigne à `this.options` AVANT l'instanciation du `@services` (phase …
- `onKernelReady(): Promise<this>` — Phase `onReady` : enregistre les fournisseurs de variables `{{ }}` built-in sur le service (tous les modules sont alors bootés).

### Fonctions (13)

#### `defineDocumentationConfig`

```ts
function defineDocumentationConfig(input?: unknown): IDocumentationConfig
```

Valide une config partielle et applique les défauts du schéma.

#### `documentationConfigJsonSchema`

```ts
function documentationConfigJsonSchema(): unknown
```

JSON Schema introspectable de la config documentation — destiné au panneau de config Studio (`/nodefony/config`), noms courts d'environnement compris.

#### `extractSearchText`

```ts
function extractSearchText(markdown: string): string
```

Prose INDEXABLE d'une page de documentation.

#### `foldText`

```ts
function foldText(text: string): string
```

Réduit un texte à sa forme comparable : minuscules, accents retirés.

#### `isSafeSlug`

```ts
function isSafeSlug(slug: string): boolean
```

Valide qu'un slug est sûr à manipuler (avant toute recherche/lecture).

#### `metaList`

```ts
function metaList(meta: Frontmatter, key: string): string[]
```

Lit une clé de frontmatter en string[] (wrappe un scalaire), ou `[]`.

#### `metaString`

```ts
function metaString(meta: Frontmatter, key: string): string
```

Lit une clé de frontmatter en string (1er élément si liste), ou `undefined`.

#### `parseFrontmatter`

```ts
function parseFrontmatter(raw: string): ParsedDoc
```

Sépare le bloc frontmatter du corps markdown et parse les métadonnées.

#### `pathToSlug`

```ts
function pathToSlug(source: DocSource, relPath: string): string
```

Construit le slug d'un fichier à partir de sa source et de son chemin relatif (POSIX, sans `.md`). Inverse jamais utilisé (slug = clé, pas chemin).

#### `rewriteInternalLinks`

```ts
function rewriteInternalLinks(markdown: string, options: RewriteLinksOptions): string
```

Réécrit les liens markdown internes d'une page en slugs navigables.

#### `scanDocsDir`

```ts
function scanDocsDir(baseDir: string, source: DocSource, exclude?: readonly string[]): Promise<ScannedDoc[]>
```

Scanne récursivement un dossier de docs et retourne les fichiers `.md` trouvés, frontmatter lu, triés par chemin relatif.

#### `searchDocs`

```ts
function searchDocs(docs: SearchableDoc[], query: string, limit?: number): IDocSearchResult
```

Classe les pages qui portent TOUS les termes, la plus pertinente d'abord.

#### `splitSearchTerms`

```ts
function splitSearchTerms(query: string): string[]
```

Termes effectivement cherchés : pliés, dédoublonnés, un caractère écarté.

### Constantes (3)

#### `ROOT_GROUPS`

```ts
const ROOT_GROUPS: ReadonlyArray<{ group: string; label: string; }>
```

Les groupes racine publiés, **dans l'ordre du menu**, avec leur libellé.

#### `ROOT_PAGES`

```ts
const ROOT_PAGES: ReadonlyArray<string>
```

Pages de `docs/` (à la racine, hors sous-dossier) publiées dans le menu, dans cet ordre. Le reste de ce dossier est du PILOTAGE — carte des phases, README du corpus, essai sur l'outillage : utile au mainteneur du framework, illisible pour qui construit une application.

#### `documentationConfigSchema`

```ts
const documentationConfigSchema: z.ZodObject<{ enabled: z.ZodDefault<z.ZodBoolean>; scan: z.ZodDefault<z.ZodObject<{ rootDir: z.ZodDefault<z.ZodString>; includeModules: z.ZodDefault<z.ZodBoolean>; includeInstalled: z.ZodDefault<z.ZodBoolean>; exclude: z.ZodDefault<z.ZodArray<z.ZodString>>; }, z.core.$strict>>; repo: z.ZodDefault<z.ZodObject<{ url: z.ZodDefault<z.ZodString>; branch: z.ZodOptional<z …
```

### Interfaces (10)

#### `IDocAudienceInfo`

```ts
interface IDocAudienceInfo
```

Une persona décrite dans l'index (clé + libellé + description courte).

- `key: DocAudience`
- `label: string`
- `desc: string`

#### `IDocPage`

```ts
interface IDocPage
```

Contenu complet d'une page renvoyé par `GET …/api/page/{slug}`.

- `slug: string`
- `title: string`
- `version?: string`
- `status?: DocStatus`
- `updated?: string` — Date de dernière modif (frontmatter `updated` ou dernier commit git).
- `source?: string` — Chemin source relatif au repo (pour traçabilité).
- `sourceUrl?: string` — URL « Modifier sur GitHub » assemblée serveur (jamais de chemin FS).
- `markdown: string` — Markdown SANS le bloc frontmatter, variables `{{ }}` résolues.

#### `IDocPageRef`

```ts
interface IDocPageRef
```

Entrée d'une page dans l'arbre (métadonnées seules, sans le markdown).

- `slug: string` — Identifiant URL-safe unique (sert de clé d'allowlist anti-traversée).
- `title: string` — Titre lisible (frontmatter `title`, sinon dérivé du nom de fichier).
- `navTitle: string` — Libellé COURT pour la navigation (frontmatter `navTitle`, repli sur `title`).
- `audience: DocAudience[]` — Personas autorisées (frontmatter `audience`).
- `version?: string` — Version de la page (frontmatter `version`, ou `"doc"`).
- `status?: DocStatus` — Statut de maturité (frontmatter `status`).
- `wip?: boolean` — `true` si la page est annoncée mais pas encore rédigée.
- `isHub?: boolean` — `true` si la page est le **hub** de sa section (`index.md`) : son point d'entrée, à présenter en premier et non comme une page parmi les autres.

#### `IDocSection`

```ts
interface IDocSection
```

Une section de l'index transverse : un groupe ordonné de pages.

- `id: string` — Identifiant stable de la section (URL-safe).
- `label: string` — Libellé affiché.
- `module?: string` — Module propriétaire (`@nodefony/x`) si la section vient d'un module.
- `pages: IDocPageRef[]` — Pages de la section.

#### `IDocTree`

```ts
interface IDocTree
```

Index transverse complet renvoyé par `GET …/api/tree`.

- `generatedAt: string` — Date ISO de génération de l'index (cache invalidé après TTL).
- `audiences: IDocAudienceInfo[]` — Personas connues (pour le sélecteur de vue / RBAC).
- `sections: IDocSection[]` — Sections de l'index.

#### `IDocumentationService`

```ts
interface IDocumentationService
```

Service public du module documentation (consommé par le controller).

- `getTree(): Promise<IDocTree>` — Construit (ou sert depuis le cache) l'index transverse des docs.
- `getPage(slug: string): Promise<IDocPage>` — Charge une page par slug (validé contre l'allowlist du scan), résout son frontmatter et ses variables `{{ }}`.
- `search(query: string, limit?: number): Promise<IDocSearchResult>` — Cherche dans les titres ET le corps des pages, et rend des extraits situés.
- `registerVar(name: string, provider: DocVarProvider): void` — Enregistre un fournisseur de variable `{{ name }}` (résolution serveur).
- `invalidate(): void` — Invalide le cache de l'index (force un rescan au prochain `getTree`).

#### `ParsedDoc`

```ts
interface ParsedDoc
```

Résultat du parse : `meta` (frontmatter) + `body` (markdown sans le bloc).

- `meta: Frontmatter`
- `body: string`

#### `RewriteLinksOptions`

```ts
interface RewriteLinksOptions
```

Options de `rewriteInternalLinks`.

- `fromDir: string` — Dossier de la page courante, relatif à la racine du projet (POSIX, sans fichier).
- `toSlug: (repoRelPath: string) => string` — Traduit un chemin de fichier relatif à la racine du projet en slug.
- `suffix?: string` — Suffixe ajouté derrière la cible traduite.

#### `ScannedDoc`

```ts
interface ScannedDoc
```

Un fichier `.md` découvert par le scan, avec son chemin RÉEL et ses métadonnées. Le `absPath` est la seule source de vérité pour lire le fichier (jamais reconstruit depuis le slug → 0 traversée de répertoire).

- `slug: string` — Clé d'allowlist URL-safe (cf `pathToSlug`).
- `relPath: string` — Chemin relatif POSIX au dossier de base scanné.
- `absPath: string` — Chemin absolu RÉEL du fichier (pour la lecture).
- `source: DocSource` — Origine (racine du projet ou module).
- `group: string` — Chemin du dossier parent (POSIX) — sert à regrouper en sections.
- `meta: Frontmatter` — Frontmatter parsé (title/audience/section/version/status/updated/source).
- `title: string` — Titre résolu (frontmatter `title`, sinon nom de fichier humanisé).
- `navTitle: string` — Libellé de NAVIGATION — court, destiné aux menus et fils d'Ariane.

#### `SearchableDoc`

```ts
interface SearchableDoc
```

Une page telle que la recherche a besoin de la voir.

- `slug: string`
- `title: string`
- `navTitle: string`
- `sectionLabel: string` — Libellé de la section d'arbre qui porte la page (« Guides », « Cœur »…).
- `body: string` — Corps de la page, frontmatter retiré.

### Types (7)

#### `DocAudience`

```ts
type DocAudience = "developer" | "devops" | "supervisor" | "admin"
```

Persona métier ciblée par une page (RBAC P6 — aujourd'hui filtre de vue).

#### `DocSource`

```ts
type DocSource = { kind: "root"; } | { kind: "module"; module: string; }
```

Source d'un fichier de doc : racine du projet ou un module.

#### `DocStatus`

```ts
type DocStatus = "stable" | "draft" | "temporary" | "experimental" | "deprecated"
```

Statut de maturité d'une page (issu du frontmatter `status`).

#### `DocVarProvider`

```ts
type DocVarProvider = () => string
```

Fournisseur d'une variable dynamique `{{ name }}` résolue côté serveur.

#### `Frontmatter`

```ts
type Frontmatter = Record<string, string | string[]>
```

Métadonnées extraites du frontmatter — valeurs scalaires ou listes.

#### `IDocumentationConfig`

```ts
type IDocumentationConfig = z.infer<typeof documentationConfigSchema>
```

Type de sortie (config normalisée + défauts appliqués).

#### `IDocumentationConfigInput`

```ts
type IDocumentationConfigInput = z.input<typeof documentationConfigSchema>
```

Type d'ENTRÉE (ce que l'utilisateur écrit dans `use()`, avant application des défauts) — tout y est optionnel. C'est CE type qui augmente le registre `NodefonyModuleConfig`, jamais la sortie : exiger la forme normalisée obligerait l'app à réécrire chaque défaut.

---

[← Toutes les références d'API](../)