API

The five packages are published together, at the same version. Most projects only need the docpensieve command; the packages below are for what goes further — a script that builds a site, a theme of your own.

Each entry comes from the JSDoc of the source, which the type checker verifies: it cannot drift from the code without the build noticing.

@docpensieve/shared

Constants, errors and slugs, shared by every package.

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.

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.

DEFAULT_THEME_CLASSES

DEFAULT_THEME_CLASSES

Class slots of the page shell.

Templates hard-code no class: they ask the theme for the class of each slot. A provider only redefines what it wants to change; everything else falls back to these values. That is what lets a single template render either dp-nav or a string of Tailwind utilities.

This table is shared: core reads it in its templates, theme extends it in its providers.

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.

Returns 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.

Returns 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.

Returns 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.

Returns 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.

Returns string — Output path, slash-separated.

slugToUrl

slugToUrl(slug, [versionSlug])

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

Returns 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.

Returns string

orderOf

orderOf(filename)

Reads the ordering weight of a prefixed file name.

Returns number — The prefix number, or Infinity when absent (sorted last).

@docpensieve/core

Configuration, loading, compilation, structured data and generation.

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.

Returns 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.

Returns Promise<DocPensieveConfig> — Normalised config.

Throws 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.

Returns DocPensieveConfig — Normalised config.

Throws ConfigError — When the config is structurally invalid.

resolveVersion

resolveVersion(config, [slug])

Finds a declared version by its slug.

Returns Version — The requested version.

Throws 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.

Returns 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.

Returns SidebarNode[]

Throws 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.

Returns Record<string, string> — Full folder slug to title.

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.

Returns string

buildRobots

buildRobots(sitemapUrl)

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

Returns 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.

Returns string

@docpensieve/theme

The theme providers and the engine that composes them.

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

The components available in every 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.

Returns 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.

Returns string

fallbackClass

fallbackClass(slot)

Converts a slot name into a fallback class.

Returns string

getThemeClasses

getThemeClasses()

@returns {Record<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.

setThemeFramework

setThemeFramework([framework])

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

Card

Card(props)

Card container.

CardBody

Documented in packages/components/src/card.js.

CardFooter

Documented in packages/components/src/card.js.

CardHeader

Documented in 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).

Column

Column(props)

Column of a row.

Throws 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.

FallbackAfter

FallbackAfter(props)

Content shown after the period.

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

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.

TimeTimer

TimeTimer(props)

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

TOOLTIP_PLACEMENTS

TOOLTIP_PLACEMENTS

Sides the bubble can sit on.

Tooltip

Tooltip(props)

Term with a tooltip.

Throws DocPensieveError — Without text, or with an unknown side.

Tree

Tree(props)

Root of a tree.

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.

Throws DocPensieveError — Outside a Tree, or without a label.

ScrollToTop

ScrollToTop(props)

Back-to-top button.

SKILL_SHAPES

SKILL_SHAPES

Shapes accepted by the gauge.

Skill

Skill(props)

Named gauge, from 0 to 100.

Throws DocPensieveError — Without a name, outside 0–100, or with an unknown shape.

LogoIcon

LogoIcon(props)

Project SVG icon, inlined in the page.

Throws DocPensieveError — Without src, or when the file cannot be read.

ForTheme

ForTheme(props)

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

Returns any

Throws 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.

Returns Promise<string> — CSS, trimmed.

Throws 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.

Returns string — Absolute path, inside the source folder.

Throws 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.

Returns 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.

builtinComponents

builtinComponents

Components shipped with DocPensieve.

createRegistry

createRegistry([userComponents])

Builds the component table passed to the MDX compiler.

Returns 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.

Returns string[] — Names sorted alphabetically.

docpensieve

The commands, callable from a script as well as from the terminal.

build

build(versionSlug, [options])

Returns Promise<void>

check

check([options])

Reads the produced site back and reports what is wrong.

Returns Promise<{ root: string, pages: number, faults: Fault[] }>

Throws 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.

Returns Promise<{ pages: number, faults: Fault[] }>

verifyMarkup

verifyMarkup(root)

Checks the markup of a generated site.

Returns Promise<{ pages: number, faults: Fault[] }>

dev

dev([options])

Returns 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.

Returns Promise<{ dir: string, theme: string, docs: boolean }>

Throws DocPensieveError — Unknown framework, project already initialised, or documentation to install missing.

serve

serve([options])

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

Throws DocPensieveError — When the folder to serve does not exist.

createStaticServer

createStaticServer(options)

Creates a static file server.

Returns import('node:http').Server

listen

listen(server, port, [attempts])

Starts listening, looking for a free port if needed.

Returns Promise<number> — The port actually used.

Throws 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.

Returns string \| null — Absolute path, or null when the target escapes root.