# API

> Tous les exports des cinq paquets, depuis leurs JSDoc.

{/* Generated by scripts/api-reference.mjs from the JSDoc of the sources: run npm run api:docs rather than editing this page. */}

Les cinq paquets se publient ensemble, à la même version. La plupart des
projets n'ont besoin que de la commande `docpensieve` ; les paquets
ci-dessous servent à ce qui va plus loin — un script qui génère un site,
un thème à vous.

Chaque entrée vient des JSDoc des sources, que le vérificateur de types
contrôle : elle ne peut pas dériver du code sans que la génération le
voie. **Les signatures et leurs descriptions restent en anglais**, comme
le code d'où elles sortent.

Pour employer l'outil plutôt que l'appeler, commencez par
[Installation](/versions/beta/fr/guide/installation/) ; les champs d'une configuration
sont dans [Configuration](/versions/beta/fr/reference/configuration/).

## `@docpensieve/shared`

Constantes, erreurs et slugs, partagés par tous les paquets.

### `DOC_EXTENSIONS`

`DOC_EXTENSIONS`

File extensions recognised as documentation pages.

### `CONFIG_FILENAME`

`CONFIG_FILENAME`

Name of the configuration file `init` writes at the project root.

`.mjs` rather than `.js`: the file is an ES module, and Node reads a `.js`
file as one only when the nearest package.json declares "type": "module".
Elsewhere it warns on every build — or refuses the file outright when that
package.json says "commonjs", as `npm init -y` now writes.

### `CONFIG_FILENAMES`

`CONFIG_FILENAMES`

Names accepted for the configuration file, in the order they are looked for.
The `.js` spelling still works in a project whose package.json declares
"type": "module".

### `THEME_FOLDER`

`THEME_FOLDER`

Folder of the project's own stylesheets, at its root. Every `.css` file in
it is appended to the site's stylesheet, after the theme's.

### `DEFAULT_OUT_DIR`

`DEFAULT_OUT_DIR`

Default output directory of a build.

### `VERSIONS_MANIFEST`

`VERSIONS_MANIFEST`

Version manifest written by every build.

### `INDEX_SLUGS`

`INDEX_SLUGS`

Page slugs treated as the root of their folder (they take the folder's own URL).

### `JSONLD_TYPES`

`JSONLD_TYPES`

JSON-LD types supported by the `jsonld.type` frontmatter field.

### `THEME_FRAMEWORKS`

`THEME_FRAMEWORKS`

CSS frameworks known to the ThemeEngine.

### `DOCUMENTATION_URL`

`DOCUMENTATION_URL`

Public address of the documentation.

Written wherever a reader could be stuck — the foot of the help, the
generated configuration, the end of `init` — so it lives in one place
rather than in each of them.

### `PAGE_LAYOUTS`

`PAGE_LAYOUTS`

Layouts accepted in a page's frontmatter.

`doc` is the documentation layout: menu on the left, table of contents on
the right, content held to reading width. `home` removes all three, which
is what a landing page expects.

### `ADMONITION_TONES`

`ADMONITION_TONES`

Tones an admonition can take: what colours it, nothing more.

Here rather than with the component: the configuration validates the kinds a
project declares, and `core` never imports `components` (ADR-002).

### `SNIPPET_LANGUAGES`

`SNIPPET_LANGUAGES`

What a block of code shows of its language: a short mark, and a colour.

The colour is the one that language is known by. It is used as an accent —
a rule above the block and the mark beside its name — never as a
background or a text colour, so it cannot fight the theme or fail a
contrast check. A project that wants none of it sets its own.

The icon name is the slug of an icon collection. It is only ever read when
a project declares a set to take it from: a documentation installed in a
project that has none must still build.

### `DocPensieveError`

`class DocPensieveError`

Expected domain error — the CLI prints it without a stack trace.

### `ConfigError`

`class ConfigError`

Configuration missing, unreadable or invalid.

### `LoaderError`

`class LoaderError`

A source file could not be read or parsed.

### `CompileError`

`class CompileError`

MDX/Markdown compilation failed.

### `StructuredDataError`

`class StructuredDataError`

Invalid `jsonld` frontmatter or inconsistent structured data.

### `ThemeError`

`class ThemeError`

Theme provider missing, invalid, or whose compilation failed.

### `GeneratorError`

`class GeneratorError`

The site could not be generated or written.

### `NotImplementedError`

`class NotImplementedError`

Milestone not implemented yet — points to the roadmap section.

### `slugify`

`slugify(input)`

Turns free text into a URL-safe slug.

Accents are decomposed then dropped (`Crème` → `creme`), which keeps URLs
readable instead of percent-encoded.

| Paramètre | Type | |
| --- | --- | --- |
| `input` | `string` |  |

**Renvoie** `string` — Lowercase slug, dash-separated.

### `filePathToSlug`

`filePathToSlug(relativePath)`

Converts a file path, relative to the version folder, into a page slug.

Ordering prefixes are removed from every segment: they sort the sidebar,
they do not build the URL.

| Paramètre | Type | |
| --- | --- | --- |
| `relativePath` | `string` | Path relative to the version folder. |

**Renvoie** `string` — Slug with no leading or trailing slash.

### `assetPathToSlug`

`assetPathToSlug(relativePath)`

Maps an asset path into URL space.

Folders follow the page rule — ordering prefix removed, segment slugified —
so that `02-guide/diagram.png` lands under `/guide/`, where the pages of the
same folder expect it. Otherwise the sorting prefix, which never shows in a
page URL, would show in the URL of its images.

The file name itself stays untouched: it is the one the author writes in
their Markdown, and rewriting it would break the reference.

| Paramètre | Type | |
| --- | --- | --- |
| `relativePath` | `string` | Path relative to the version folder. |

**Renvoie** `string` — Output path, slash-separated.

### `blankSegments`

`blankSegments(relativePath)`

Segments of a path that leave nothing behind once slugified.

`slugify` only keeps Latin letters and digits: a name made entirely of
ideograms, or of punctuation, vanishes. For a page, that meant taking the
home page's URL; for a folder, disappearing from the address.

| Paramètre | Type | |
| --- | --- | --- |
| `relativePath` | `string` | Path relative to the version folder. |

**Renvoie** `string[]` — The offending segments, extension removed.

### `dirPathToSlug`

`dirPathToSlug(relativePath)`

Maps a **folder** path into URL space.

Sibling of `assetPathToSlug`, but with no file name to spare: every segment
goes through the page rule. Applying `assetPathToSlug` to a folder left its
last segment untouched — `02-guide` stayed `02-guide` — and every relative
target of a page in that folder missed the file actually copied.

| Paramètre | Type | |
| --- | --- | --- |
| `relativePath` | `string` | Path relative to the version folder. |

**Renvoie** `string` — Output path, slash-separated.

### `slugToUrl`

`slugToUrl(slug, [versionSlug])`

Converts a page slug into an absolute site URL (trailing slash included).

| Paramètre | Type | |
| --- | --- | --- |
| `slug` | `string` | Slug produced by \{@link filePathToSlug\}. |
| `[versionSlug]` | `string` | When given, prefixes `/versions/<version>`. |

**Renvoie** `string` — URL starting and ending with `/`.

### `humanizeSlug`

`humanizeSlug(segment)`

Turns a slug segment back into a readable label.

A deliberate, imperfect fallback: since `slugify` dropped the accents,
`creme-brulee` comes back as “Creme brulee”. Only use it when there is no
real title — the sidebar and the breadcrumb prefer the frontmatter title.

| Paramètre | Type | |
| --- | --- | --- |
| `segment` | `string` |  |

**Renvoie** `string`

### `orderOf`

`orderOf(filename)`

Reads the ordering weight of a prefixed file name.

| Paramètre | Type | |
| --- | --- | --- |
| `filename` | `string` |  |

**Renvoie** `number` — The prefix number, or `Infinity` when absent (sorted last).

### `UI_STRINGS`

`UI_STRINGS`

The shipped languages.

### `DEFAULT_LANGUAGE`

`DEFAULT_LANGUAGE`

Language used when nothing else is known.

### `uiStrings`

`uiStrings([lang], [overrides])`

The wording of a language, completed by English for anything it omits.

| Paramètre | Type | |
| --- | --- | --- |
| `[lang]` | `string` | Language code, `fr` or `fr-CA`. |
| `[overrides]` | `Record<string, Partial<UiStrings>>` | Wording declared by the project. |

**Renvoie** `UiStrings`

### `pageCount`

`pageCount(count, strings, [lang])`

Counts pages in the language of the page.

The plural category comes from the language itself, through the CLDR rules
`Intl` carries: `count === 1` is an English rule and gets French wrong on
zero — "0 page", not "0 pages" — and has nothing to say about Polish or
Arabic, which have four and six categories.

| Paramètre | Type | |
| --- | --- | --- |
| `count` | `number` |  |
| `strings` | `UiStrings` |  |
| `[lang]` | `string` | Language of the page. |

**Renvoie** `string` — For instance `12 pages` or `1 page`.

### `textDirection`

`textDirection([lang])`

Writing direction of a language, for the `dir` attribute.

Read from the language rather than from a list of our own: `Intl` carries
what CLDR knows, and a list would go stale the day someone translates into
a language nobody thought of.

| Paramètre | Type | |
| --- | --- | --- |
| `[lang]` | `string` |  |

**Renvoie** `'ltr' \| 'rtl'` — `ltr` when the language is unknown — the safe default, and what every page did before this existed.

### `isLanguageCode`

`isLanguageCode(value)`

Whether a string names a language, as BCP 47 and CLDR understand it.

The standard is BCP 47, and `Intl` carries it: a regex of our own refused
`zh-Hans-CN`, which is valid, and accepted shapes that are not. Well formed
is not the same as real, though — BCP 47 allows a language subtag of five
to eight letters, so `francais` passes that check and would land in the
markup as `lang="francais"`, a value no browser maps to a language. CLDR
knows which tags name one; the subtag alone is asked, so that a region, a
script or a private extension does not get in the way.

| Paramètre | Type | |
| --- | --- | --- |
| `value` | `string` |  |

**Renvoie** `boolean`

### `languageName`

`languageName(code, [inLang])`

Name of a language, written in a language.

| Paramètre | Type | |
| --- | --- | --- |
| `code` | `string` | Language code. |
| `[inLang]` | `string` | Language the name is written in. |

**Renvoie** `string` — The name, or the code itself when nothing names it.

## `@docpensieve/core`

Configuration, chargement, compilation, données structurées et génération.

### `DEFAULT_CONFIG`

`DEFAULT_CONFIG`

Values applied when the user config leaves them out.

The type is spelled out: without it, TypeScript would infer
`versions: never[]` from the empty array and refuse every read of its
elements elsewhere in the file.

### `defineConfig`

`defineConfig(config)`

Identity over the config, used only for autocompletion and type checking
in the editor.

| Paramètre | Type | |
| --- | --- | --- |
| `config` | `T` |  |

**Renvoie** `T`

### `loadConfig`

`loadConfig([cwd])`

Loads the configuration file of a project folder.

`docpensieve.config.mjs` is looked for first, then `docpensieve.config.js`,
which a project whose package.json declares "type": "module" can still use.

| Paramètre | Type | |
| --- | --- | --- |
| `[cwd]` | `string` | Project root. Default: `process.cwd()`. |

**Renvoie** `Promise<DocPensieveConfig>` — Normalised config.

**Lève** `ConfigError` — When no file, or two, are found, or when the file does not load or exports no object.

### `normalizeConfig`

`normalizeConfig(userConfig)`

Merges the user config with the defaults and validates it.

| Paramètre | Type | |
| --- | --- | --- |
| `userConfig` | `Record<string, unknown>` |  |

**Renvoie** `DocPensieveConfig` — Normalised config.

**Lève** `ConfigError` — When the config is structurally invalid.

### `resolveVersion`

`resolveVersion(config, [slug])`

Finds a declared version by its slug.

| Paramètre | Type | |
| --- | --- | --- |
| `config` | `DocPensieveConfig` | Normalised config. |
| `[slug]` | `string` | Slug to look for. Omitted: the "current" version. |

**Renvoie** `Version` — The requested version.

**Lève** `ConfigError` — When the slug does not exist.

### `DocLoader`

`class DocLoader`

Walks a version folder and produces the list of documents.

### `Compiler`

`class Compiler`

Compiles an MDX/Markdown source into an HTML fragment.

### `StructuredDataBuilder`

`class StructuredDataBuilder`

Assembles a schema.org graph for a page.

### `SiteGenerator`

`class SiteGenerator`

Generates the static site of one or more versions.

### `buildSidebar`

`buildSidebar(docs, [toUrl], [options])`

Builds the navigation tree of a version.

The order is the `DocLoader`'s, which has already sorted: index page first,
then numeric prefixes, then alphabetical. Nothing is re-sorted here, which
guarantees that the sidebar follows the reading order of the files exactly.

That order has a useful consequence: since `guide/index.md` is loaded
before `guide/installation.md`, the “guide” category receives its real
title before a child page creates it with a default one.

| Paramètre | Type | |
| --- | --- | --- |
| `docs` | `import('./loader.js').Doc[]` | Documents in loader order. |
| `[toUrl]` | `(doc: import('./loader.js').Doc) => string` | Turns a document into a URL. By default, the document's URL as is. |
| `[options]` | `{ brand?: string }` | `brand` is the name shown in the header: a root entry carrying exactly that title is dropped, since the brand already leads to that page. The same word twice, an inch apart, tells the reader nothing. |

**Renvoie** `SidebarNode[]`

### `buildSidebarFromDescription`

`buildSidebarFromDescription(description, docs, [toUrl], [options])`

Builds the navigation tree of a version from a description.

The description is an array of entries, kept in the order written:

- `"guide/installation"` — a page, by its path within the version, as in
  its URL; `"/"` is the home page. Its title becomes the label.
- `{ "page": "guide/installation", "label": "Install" }` — the same, with a
  label of its own.
- `{ "label": "Guide", "items": [ … ], "page": "guide" }` — a category,
  clickable when it names a page.
- `{ "label": "Repository", "href": "https://…" }` — a link outside the site.
- `{ "auto": "docpensieve" }` — the automatic tree of a folder: a section
  keeps its own menu without listing its pages one by one.

A page left out stays published: it is only absent from the menu, which is
how a page is kept off it.

| Paramètre | Type | |
| --- | --- | --- |
| `description` | `unknown` | Parsed content of the description file. |
| `docs` | `import('./loader.js').Doc[]` | Documents of the version. |
| `[toUrl]` | `(doc: import('./loader.js').Doc) => string` | As for `buildSidebar`. |
| `[options]` | `{ source?: string }` | `source` names the file in messages. |

**Renvoie** `SidebarNode[]`

**Lève** `ConfigError` — For a path that names no page, a page listed twice, or an entry of no known kind.

### `collectSectionTitles`

`collectSectionTitles(docs)`

Collects folder titles, for the breadcrumb.

Only folders with an index page have a known title; the others will be
humanised from their slug by `StructuredDataBuilder`.

| Paramètre | Type | |
| --- | --- | --- |
| `docs` | `import('./loader.js').Doc[]` |  |

**Renvoie** `Record<string, string>` — Full folder slug to title.

### `foldSidebar`

`foldSidebar(nodes, [currentUrl])`

| Paramètre | Type | |
| --- | --- | --- |
| `nodes` | `SidebarNode[]` |  |
| `[currentUrl]` | `string` | URL of the page being rendered. |

**Renvoie** `FoldedNode[]`

### `MARKDOWN_COPY`

`MARKDOWN_COPY`

File a page's Markdown copy is written to, beside its HTML.

### `buildFeed`

`buildFeed(pages, site)`

Builds the RSS feed of the dated pages, newest first.

Only a page with a `date` enters it: a documentation page without one is
reference material, not news, and dating it at build time would announce
every page again at every build.

| Paramètre | Type | |
| --- | --- | --- |
| `pages` | `PublishedPage[]` | Pages of the current version. |
| `site` | `{ projectName: string, siteUrl: string, homeUrl: string, feedUrl: string, lang?: string, }` | `homeUrl` and `feedUrl` are absolute. |

**Renvoie** `string`

### `buildLlms`

`buildLlms(pages, site)`

Builds `llms.txt`: the index of a documentation, for a reader that is a
program.

Follows the proposal as it stands: a title, a one-line summary, then a list
of links, each to the Markdown copy of a page — the address of the page with
`index.html.md` appended, since the pages are folders. A program reads that
copy as the author wrote it, instead of prying the text out of the markup.

| Paramètre | Type | |
| --- | --- | --- |
| `pages` | `PublishedPage[]` | Pages of the version the site serves first. |
| `site` | `{ projectName: string, summary?: string, base?: string }` | `base` makes each link absolute when the site has a public address, and root-relative otherwise. |

**Renvoie** `string`

### `buildRobots`

`buildRobots(sitemapUrl)`

Builds `robots.txt`, which lets every crawler in and names the sitemap.

| Paramètre | Type | |
| --- | --- | --- |
| `sitemapUrl` | `string` | Absolute address of the sitemap. |

**Renvoie** `string`

### `buildSitemap`

`buildSitemap(pages, siteUrl)`

Builds `sitemap.xml`.

`lastmod` is the page's `modified` date, or failing that its `date`; a page
that carries neither is listed without one rather than with a made-up date.

| Paramètre | Type | |
| --- | --- | --- |
| `pages` | `PublishedPage[]` | Pages of the versions to list. |
| `siteUrl` | `string` | Public address of the site: the sitemap only holds absolute addresses. |

**Renvoie** `string`

### `markdownCopy`

`markdownCopy(frontmatter, content, [resolve])`

The Markdown copy of a page: its source, as the author wrote it.

The title is added when the page does not open on one, since a program
handed the copy alone has no frontmatter to read it from. What a component
draws at build time is not in the copy — a snippet's file, a grid of cards:
the copy says what was written, not what was rendered.

The links are the exception. The build resolves them from the folder of the
source file, and a version-root one from the version: read from where the
copy is served, as written, they would lead nowhere. `resolve` gives each the
address the HTML page carries.

| Paramètre | Type | |
| --- | --- | --- |
| `frontmatter` | `{ title?: string, description?: string }` |  |
| `content` | `string` | Source of the page, frontmatter removed. |
| `[resolve]` | `(target: string) => string \| null` | Address of a target on the site, or `null` to keep it as written. |

**Renvoie** `string`

### `buildAuthorTable`

`buildAuthorTable(description, options)`

Turns the JSON description of a version into a table of authors.

| Paramètre | Type | |
| --- | --- | --- |
| `description` | `unknown` | Parsed content of the file. |
| `options` | `{ source: string }` | `source` names the file in errors. |

**Renvoie** `Map<string, Author>`

**Lève** `ConfigError` — When the shape is wrong, naming the offending entry.

### `buildByline`

`buildByline(frontmatter, [table], [where], [locale])`

Assembles what the head of a page shows, or nothing when it has none of it.

| Paramètre | Type | |
| --- | --- | --- |
| `frontmatter` | `Record<string, any>` |  |
| `[table]` | `Map<string, Author>` |  |
| `[where]` | `string` | Page named in a date error. |
| `[locale]` | `string` | Locale the dates are written in. |

**Renvoie** `Byline \| null`

**Lève** `ConfigError` — When a date cannot be read.

### `readDate`

`readDate(value, field, where, [locale])`

Reads a date of the frontmatter, and gives it in both forms: the machine one
for `<time datetime>`, the readable one for the reader.

A date is often written unquoted in YAML, which parses it as a Date; quoted,
it arrives as text. Both are accepted, anything unreadable is refused rather
than shown as `Invalid Date`.

| Paramètre | Type | |
| --- | --- | --- |
| `value` | `unknown` |  |
| `field` | `string` | Name of the field, for the error message. |
| `where` | `string` | Page the date comes from. |
| `[locale]` | `string` | Locale the label is written in. Default: `en-GB`. |

**Renvoie** `{ iso: string, label: string } \| null` — `null` when absent.

**Lève** `ConfigError` — When the value is not a date.

### `resolvePageAuthors`

`resolvePageAuthors(value, [table])`

The authors of a page, in the order the frontmatter names them.

A key the table does not describe is not an error: the name is shown as
written. It is what lets a project name its authors before describing them,
and what keeps pages written before the file working.

| Paramètre | Type | |
| --- | --- | --- |
| `value` | `unknown` | `authors` from the frontmatter: one name or a list. |
| `[table]` | `Map<string, Author>` |  |

**Renvoie** `Author[]`

### `SNIPPET_LANGUAGES`

`SNIPPET_LANGUAGES`

Languages an extension announces, where the extension is not the name Shiki
knows. Anything absent is passed on as it is written: Shiki knows far more
languages than this table needs to repeat.

### `snippetLanguage`

`snippetLanguage(file)`

Language of a file, from its name.

| Paramètre | Type | |
| --- | --- | --- |
| `file` | `string` | Path or name of the file. |

**Renvoie** `string` — A language for the highlighter, or `'text'` when the name says nothing — an extensionless file is not a reason to fail.

### `snippetLines`

`snippetLines(text, [what])`

The lines a snippet keeps, of the whole file.

A range is quick to write and ages badly: it means line 12 of the file as
it is today. A region is a marker left in the source itself — the comment
convention editors already fold on — and it follows the code when it moves,
which is the whole point of naming a file rather than copying it.

| Paramètre | Type | |
| --- | --- | --- |
| `text` | `string` | Content of the file. |
| `[what]` | `{ lines?: string, region?: string, file?: string }` | `lines` is `12`, `12-40`, `12-` or `-40`; `region` is the name marked in the file. |

**Renvoie** `string` — The lines kept, their common indentation removed.

**Lève** `CompileError` — A range that reads backwards, or a region no marker opens or closes.

### `snippetPath`

`snippetPath(source, context)`

The file a snippet names, as an absolute path.

Two ways to write it, and they read differently on purpose: `./` and `../`
start from the page, as a link does, while anything else starts from the
root of the project — `src/index.js` means the same thing from every page,
which is what a file of source code needs.

| Paramètre | Type | |
| --- | --- | --- |
| `source` | `string` | What the page wrote. |
| `context` | `{ filepath?: string, rootDir?: string }` | Page being compiled, and root of the project. |

**Renvoie** `string` — Absolute path of the file to read.

**Lève** `CompileError` — Empty source, a relative path with no page to start from, or a file outside the project.

## `@docpensieve/theme`

Les providers de thème et le moteur qui les compose.

### `BaseThemeProvider`

`class BaseThemeProvider`

Base class to extend in order to plug in a CSS framework.

A provider generates no HTML: it supplies CSS, variables and a table of
class aliases. That is what lets a single template render correctly under
Tailwind as well as under the custom theme.

### `CustomProvider`

`class CustomProvider`

Custom theme: hand-written CSS, no dependency.

### `DEFAULT_TOKENS`

`DEFAULT_TOKENS`

Palette and measures of the light theme.

Dark mode does not live here: it fits in two blocks of `custom.css`, since
a flat table of variables cannot express a media query.

### `TailwindProvider`

`class TailwindProvider`

Tailwind theme: on-demand compilation of the classes actually used.

### `ThemeEngine`

`class ThemeEngine`

Combines several providers into a single CSS output.

## `@docpensieve/components`

Les composants disponibles dans chaque page.

### `classNames`

`classNames(parts)`

Joins classes while ignoring falsy values.

A minimal equivalent of `clsx`: one more dependency is not worth it for six
lines.

| Paramètre | Type | |
| --- | --- | --- |
| `parts` | `...unknown` |  |

**Renvoie** `string \| undefined` — `undefined` when nothing is left, to avoid a `class=""` in the produced HTML.

### `cls`

`cls(slot, modifiers)`

Class of a slot, variants included.

| Paramètre | Type | |
| --- | --- | --- |
| `slot` | `string` | Slot name. |
| `modifiers` | `...unknown` | Variants, each one suffixed as `--variant`. Falsy values are ignored, which allows writing `cls('card', shadow && shadow)`. |

**Renvoie** `string`

### `fallbackClass`

`fallbackClass(slot)`

Converts a slot name into a fallback class.

| Paramètre | Type | |
| --- | --- | --- |
| `slot` | `string` |  |

**Renvoie** `string`

### `getThemeClasses`

`getThemeClasses()`

@returns \{Record&lt;string, string>\} The current table, for inspection.

### `getThemeFramework`

`getThemeFramework()`

@returns \{string\} The active framework, or `''` when none was announced.

### `setThemeClasses`

`setThemeClasses([classes])`

Declares the theme table for the whole compilation.

| Paramètre | Type | |
| --- | --- | --- |
| `[classes]` | `Record<string, string>` |  |

### `setThemeFramework`

`setThemeFramework([framework])`

Declares the framework of the active theme, which `ForTheme` reads.

| Paramètre | Type | |
| --- | --- | --- |
| `[framework]` | `string` |  |

### `ADMONITION_KINDS`

`ADMONITION_KINDS`

The kinds the tool ships with, each a label and a tone.

`alert` and `danger` share a tone and differ in their label and their icon:
one calls for attention now, the other warns of what a wrong move costs.

### `Admonition`

`Admonition(props)`

Block set apart from the text.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, type?: string, title?: string, }` | `type` names the kind; `title` replaces its label for this block alone. |

**Lève** `DocPensieveError` — When the kind is unknown.

### `getAdmonitionKinds`

`getAdmonitionKinds()`

@returns \{Record&lt;string, \{ label: string, tone: string, icon?: string \}>\} Every kind available.

### `setAdmonitionKinds`

`setAdmonitionKinds([kinds])`

Declares the kinds of the project, beside the ones shipped.

| Paramètre | Type | |
| --- | --- | --- |
| `[kinds]` | `Record<string, { label: string, tone: string, icon?: string }>` |  |

### `Card`

`Card(props)`

Card container.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `PartProps & { elevated?: boolean, href?: string }` | `elevated` adds a shadow. `href` makes the whole card clickable, rather than a link on the title alone that would leave the rest inert. |

### `CardBody`

Documenté dans `packages/components/src/card.js`.

### `CardFooter`

Documenté dans `packages/components/src/card.js`.

### `CardHeader`

Documenté dans `packages/components/src/card.js`.

### `CardImage`

`CardImage(props)`

Image at the top of a card.

`src` resolves as in Markdown — relative to the page, absolute from the
version root. The compiler plugins cannot handle it: they work on the
Markdown tree, before React renders anything. So the component does it
itself (ADR-006).

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, src?: string, alt?: string, title?: string, srcSet?: string, sizes?: string, loading?: 'lazy' \| 'eager', }` | `alt` defaults to the empty string: without that attribute, a screen reader would announce the file URL. |

### `Cards`

`Cards(props)`

Grid of cards for the children of a folder.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, of?: 'all' \| 'series' \| 'pages', from?: string, }` | `of` narrows the grid to the sub-folders (`'series'`) or to the pages beside the index (`'pages'`); `from` reads another folder, named by its slug, instead of the one holding the page. |

**Lève** `Error` — When the page list is missing, or `from` names nothing.

### `Column`

`Column(props)`

Column of a row.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, span?: number }` | `span` is the number of tracks taken out of twelve — `span={6}` for a half, `span={8}` for two thirds. Twelve because twelve divides by two, three, four and six. Without `span`, the columns share the space equally. |

**Lève** `DocPensieveError` — Outside a `Columns`, or when the row mixes columns with and without a width.

### `Columns`

`Columns(props)`

Row of columns.

The gap is set through `className` or `style`, with the theme's utilities:
the grid recomputes the widths by itself.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any }` |  |

### `Menu`

`Menu(props)`

Menu of links.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, label?: string, }` | `label` names the menu for screen readers, and labels the button it folds into on a narrow screen. |

### `MenuGroup`

`MenuGroup(props)`

Group of entries, folded under a title.

In the row it opens as a panel below its title; folded, it unfolds in place
rather than over the rest — on a narrow screen a panel would open off
screen.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, title?: string, }` |  |

**Lève** `DocPensieveError` — Outside a `Menu`, or without a title.

### `MenuLink`

`MenuLink(props)`

Entry of a menu.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, href?: string, }` |  |

**Lève** `DocPensieveError` — Outside a `Menu`, or without a target.

### `FallbackAfter`

`FallbackAfter(props)`

Content shown after the period.

Without a wrapper, for the same reason as \{@link FallbackBefore\}.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ children?: any, end?: string }` |  |

### `FallbackBefore`

`FallbackBefore(props)`

Content shown before the period.

No wrapper: a `span` around the author's content would become invalid
markup as soon as they write a paragraph in it — which happens as soon as a
blank line separates their text. The content therefore keeps its nature,
inline or block.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ children?: any, start?: string }` |  |

### `TimeTimer`

`TimeTimer(props)`

Shows its content during a period, with fallbacks before and after.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ date?: string, start?: string, duration?: string, strict?: boolean, children?: any, now?: Date, }` | `now` only exists for tests: without it, the build moment stands. |

### `TOOLTIP_PLACEMENTS`

`TOOLTIP_PLACEMENTS`

Sides the bubble can sit on.

### `Tooltip`

`Tooltip(props)`

Term with a tooltip.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, text?: string, placement?: string, }` | `text` is the content of the bubble; the children are the term it explains. |

**Lève** `DocPensieveError` — Without text, or with an unknown side.

### `Tree`

`Tree(props)`

Root of a tree.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any }` |  |

### `TreeItem`

`TreeItem(props)`

Entry of a tree.

With children, it is a collapsible branch; without, a leaf. The difference
is read from the writing, with no prop to set.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, label?: any, open?: boolean, }` | `open` expands the branch as soon as the page opens. |

**Lève** `DocPensieveError` — Outside a `Tree`, or without a label.

### `ScrollToTop`

`ScrollToTop(props)`

Back-to-top button.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, label?: string, }` | `label` is read by screen readers. The children replace the arrow with whatever you want. |

### `SKILL_SHAPES`

`SKILL_SHAPES`

Shapes accepted by the gauge.

### `Skill`

`Skill(props)`

Named gauge, from 0 to 100.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, name?: any, level?: number, showValue?: boolean, shape?: string, icon?: any, color?: string, label?: string, }` | `children` stands as a comment under the gauge. `showValue` hides the numeric percentage without touching what the gauge announces. `shape` picks between the bar and the circle. `icon` goes before the name — a `LogoIcon` fits there. `color` tints the fill: any CSS colour, the accent colour by default. `label` names the gauge for screen readers when `name` is not text. |

**Lève** `DocPensieveError` — Without a name, outside 0–100, or with an unknown shape.

### `Calendar`

`Calendar(props)`

A calendar of the days its events fall on.

Every month from the first event to the last is drawn, so that an empty
month between two others is not silently skipped — a gap is something a
reader should see.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, label?: string, compact?: boolean, }` | `label` names the calendar for screen readers. `compact` asks for the small model at every width; a narrow screen takes it anyway, since seven columns of full cells there give each day a few millimetres. |

**Lève** `DocPensieveError` — Without an event, or with a child that is not one.

### `Event`

`Event(props)`

One event of a calendar. Rendered by its calendar, never on its own.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ date?: string, label?: string, href?: string }` |  |

**Renvoie** `any` — Never: it is the calendar that draws its events, and this function exists to be recognised among a calendar children — and to say so when it stands anywhere else.

**Lève** `DocPensieveError` — Always, outside a calendar.

### `firstWeekday`

`firstWeekday(year, month)`

The weekday a month starts on, counted from Monday.

Zeller's congruence rather than `Date`: no time zone can move a day that was
never a moment.

| Paramètre | Type | |
| --- | --- | --- |
| `year` | `number` |  |
| `month` | `number` |  |

**Renvoie** `number` — 0 for Monday, 6 for Sunday.

### `monthGrid`

`monthGrid(year, month)`

The weeks of a month, each of seven cells.

| Paramètre | Type | |
| --- | --- | --- |
| `year` | `number` |  |
| `month` | `number` |  |

**Renvoie** `(number \| null)[][]` — `null` where the cell belongs to no day.

### `readDay`

`readDay(value)`

Reads a `YYYY-MM` or `YYYY-MM-DD`.

Parsed rather than handed to `new Date()`: that reads a bare date as UTC and
a dated-and-timed one as local, so a calendar built in one time zone showed
an event a day early in another.

| Paramètre | Type | |
| --- | --- | --- |
| `value` | `string` |  |

**Renvoie** `{ year: number, month: number, day: number } \| null`

### `HERO_ALIGNMENTS`

`HERO_ALIGNMENTS`

How the words sit when the banner is a single column.

### `HERO_SIZES`

`HERO_SIZES`

How much room it takes. `full` is the height of the screen.

### `HERO_TONES`

`HERO_TONES`

Tones a banner can take.

The same ones an admonition carries: a theme defines a colour per tone, not
a colour per component, so a project that gives `attention` its own colour
gives it to both at once.

### `Hero`

`Hero(props)`

Head of a page: a name, a sentence, and the way in.

A `HeroVisual` among its children turns it into two columns — the words on
one side, the picture on the other — which is what a landing page does when
it has something to show. Nothing to declare: having a visual is what makes
it a split.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, align?: string, size?: string, tone?: string, frame?: boolean, }` | `align` is `center` (the default) or `start`; `size` is `small`, `medium`, `large` or `full`; `tone` names the colour it is lit with; `frame` draws the panel a banner does not have by default. |

**Lève** `DocPensieveError` — With an alignment, a size or a tone that does not exist.

### `HeroActions`

`HeroActions(props)`

Row of ways in, under the sentence of a banner.

Its children are links, which Markdown writes as links: the row is what
turns them into something to press, and the first one into the one meant.
One primary action and one alternative is the shape that reads: a row of
five is a row of none.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any }` |  |

### `HeroText`

`HeroText(props)`

The words of a banner, when it also has something to show.

Only needed in a split: on its own, a banner's children are its words
already.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any }` |  |

### `HeroVisual`

`HeroVisual(props)`

The picture, the screenshot or the diagram beside the words.

Its presence is what makes a banner a split: a landing page with something
to show shows it, and one without stays a single column.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any }` |  |

### `Snippet`

`Snippet(props)`

A code block, framed and labelled.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, children?: any, source?: string, title?: string, lang?: string, lines?: string, region?: string, collapsed?: boolean, icon?: string, }` | `source` names a file of the project, read at generation; `lines` or `region` keep part of it; `title` replaces the file name shown above the block. Without `source`, the block is the one written in the page. |

**Lève** `DocPensieveError` — With neither a file nor a block of its own.

### `getSnippetIcons`

`getSnippetIcons()`

@returns \{string\} The collection in use, or `''`.

### `setSnippetIcons`

`setSnippetIcons([prefix])`

Declares the collection snippet icons are taken from.

| Paramètre | Type | |
| --- | --- | --- |
| `[prefix]` | `string` | Prefix of an icon collection, `simple-icons`. |

### `LogoIcon`

`LogoIcon(props)`

Project SVG icon, inlined in the page.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ className?: string, style?: object, src?: string, label?: string, size?: string, }` | `label` describes the icon; without it the icon is treated as decorative and hidden from screen readers — which is right when nearby text already says the same thing. `size` accepts any CSS length. |

**Lève** `DocPensieveError` — Without `src`, or when the file cannot be read.

### `ForTheme`

`ForTheme(props)`

Renders its children only when the site's theme is `framework`.

| Paramètre | Type | |
| --- | --- | --- |
| `props` | `{ framework?: string, children?: any }` |  |

**Renvoie** `any`

**Lève** `DocPensieveError` — For a framework the configuration does not know, or when no theme was announced.

### `componentsCss`

`componentsCss()`

Reads the default look of the components.

It is concatenated with the theme's by the caller: a provider that
redefines a slot replaces the `dp-*` class with its own, and these rules
then stop applying by themselves.

**Renvoie** `Promise<string>` — CSS, trimmed.

**Lève** `DocPensieveError` — When the stylesheet is missing.

### `getSiteContext`

`getSiteContext()`

@returns \{SiteContext\} The current context.

### `resolveFile`

`resolveFile(target)`

Resolves a target into a file path, for a resource read at build time.

Same landmarks as for a URL, mapped to the disk: a relative target starts
from the page's file, an absolute one from the version folder. Nothing can
leave that folder — a page does not read the rest of the machine.

| Paramètre | Type | |
| --- | --- | --- |
| `target` | `string` |  |

**Renvoie** `string` — Absolute path, inside the source folder.

**Lève** `Error` — When the context is missing or the target escapes it.

### `resolveUrl`

`resolveUrl(target)`

Resolves a target written by an author into a site URL.

Same rules as for Markdown content: a relative target resolves against the
page's folder, an absolute target starts from the version root.

| Paramètre | Type | |
| --- | --- | --- |
| `target` | `string \| undefined` |  |

**Renvoie** `string \| undefined` — The resolved target, or as is when external.

### `setSiteContext`

`setSiteContext([page])`

Declares the page being rendered.

Set by the generator before every page, like the class table.

| Paramètre | Type | |
| --- | --- | --- |
| `[page]` | `Partial<SiteContext>` |  |

### `builtinComponents`

`builtinComponents`

Components shipped with DocPensieve.

### `createRegistry`

`createRegistry([userComponents])`

Builds the component table passed to the MDX compiler.

| Paramètre | Type | |
| --- | --- | --- |
| `[userComponents]` | `Record<string, Function>` | Project components, which override the built-in components of the same name. |

**Renvoie** `Record<string, Function>` — Table ready for @mdx-js/mdx.

### `listComponentNames`

`listComponentNames(registry)`

Lists the available component names — useful for a readable error message
when an `.mdx` references an unknown component.

| Paramètre | Type | |
| --- | --- | --- |
| `registry` | `Record<string, Function>` |  |

**Renvoie** `string[]` — Names sorted alphabetically.

## `docpensieve`

Les commandes, appelables depuis un script comme depuis le terminal.

### `build`

`build(versionSlug, [options])`

| Paramètre | Type | |
| --- | --- | --- |
| `versionSlug` | `string \| undefined` | Version to generate, or all of them when omitted. |
| `[options]` | `{ out?: string, cwd?: string }` |  |

**Renvoie** `Promise<void>`

### `check`

`check([options])`

Reads the produced site back and reports what is wrong.

| Paramètre | Type | |
| --- | --- | --- |
| `[options]` | `{ dir?: string, cwd?: string }` |  |

**Renvoie** `Promise<{ root: string, pages: number, faults: Fault[] }>`

**Lève** `DocPensieveError` — When the folder does not exist, or when something is left to fix — the exit code is then that of an expected error, which is enough to fail a continuous integration run.

### `verifyLinks`

`verifyLinks(root, [baseUrl])`

Checks the internal links of a generated site.

Exported apart from the command: it reads no configuration and addresses no
one, which makes it usable elsewhere and testable on its own.

| Paramètre | Type | |
| --- | --- | --- |
| `root` | `string` | Folder of the produced site. |
| `[baseUrl]` | `string` | Deployment prefix, slashes included. |

**Renvoie** `Promise<{ pages: number, faults: Fault[] }>`

### `verifyMarkup`

`verifyMarkup(root)`

Checks the markup of a generated site.

| Paramètre | Type | |
| --- | --- | --- |
| `root` | `string` | Folder of the produced site. |

**Renvoie** `Promise<{ pages: number, faults: Fault[] }>`

### `dev`

`dev([options])`

| Paramètre | Type | |
| --- | --- | --- |
| `[options]` | `{ port?: number, host?: string, cwd?: string }` |  |

**Renvoie** `Promise<{ server: import('node:http').Server, watcher: import('chokidar').FSWatcher, port: number, url: string, close: () => Promise<void>, }>`

### `init`

`init([dir], [options])`

Sets up a documentation project.

| Paramètre | Type | |
| --- | --- | --- |
| `[dir]` | `string` | Target folder, created if needed. |
| `[options]` | `{ name?: string, theme?: string, siteUrl?: string, version?: string, translation?: string, yes?: boolean, force?: boolean, minimal?: boolean, }` | `minimal` leaves DocPensieve's documentation out of the site; `translation` is the code of a second language, `fr` for instance. |

**Renvoie** `Promise<{ dir: string, theme: string, docs: boolean, translation: string, }>`

**Lève** `DocPensieveError` — Unknown framework, unknown language, project already initialised, or documentation to install missing.

### `serve`

`serve([options])`

| Paramètre | Type | |
| --- | --- | --- |
| `[options]` | `{ port?: number, host?: string, dir?: string, cwd?: string }` |  |

**Renvoie** `Promise<{ server: import('node:http').Server, port: number, url: string }>`

**Lève** `DocPensieveError` — When the folder to serve does not exist.

### `createStaticServer`

`createStaticServer(options)`

Creates a static file server.

| Paramètre | Type | |
| --- | --- | --- |
| `options` | `{ root: string, basePath?: string, inject?: string \| null, onReload?: (send: () => void) => void, }` | `basePath` is the prefix under which the site is mounted: it must reflect the configuration's `baseUrl`, otherwise the links of the pages do not resolve locally. `inject` is an HTML fragment inserted before `</body>` — the development server uses it for its reload script, which leaves the generated output intact. |

**Renvoie** `import('node:http').Server`

### `listen`

`listen(server, port, [attempts], [host])`

Starts listening, looking for a free port if needed.

On this machine only, unless asked otherwise. Called without a host, Node
listens on every interface: anyone on the same network — a café, a
coworking space — could read the site being written, drafts included.

| Paramètre | Type | |
| --- | --- | --- |
| `server` | `import('node:http').Server` |  |
| `port` | `number` | Desired port. |
| `[attempts]` | `number` | Number of ports tried from `port` on. |
| `[host]` | `string` | Address to listen on. `0.0.0.0` opens it to the network, which a phone on the same wifi needs. |

**Renvoie** `Promise<number>` — The port actually used.

**Lève** `DocPensieveError` — When no port is free in the range.

### `resolveRequestPath`

`resolveRequestPath(pathname, root)`

Resolves a request URL into a file path, without leaving the root.

| Paramètre | Type | |
| --- | --- | --- |
| `pathname` | `string` | Request path, `basePath` already removed. |
| `root` | `string` | Served folder. |

**Renvoie** `string \| null` — Absolute path, or `null` when the target escapes `root`.