DocPensieve

Your Markdown and MDX files become a static site. No runtime to load, one version per branch, structured data derived from the frontmatter.

Get started See the components

Guide

From installation to deployment, in order.

Components

Nine components usable without an import, none of them with JavaScript.

Reference

Commands, configuration, frontmatter and theme.

Architecture

How a page becomes HTML, and why it works that way.

In three commands

npx docpensieve init my-site
cd my-site
npx docpensieve dev

The first one asks a few questions — detailed below — then sets up a configuration and a documentation folder; the last one opens a server that rebuilds on every save.

Nothing else to install: the build runs on your machine, and the produced site only needs a file host.

What you get

dist
- index.html
- versions.json
- versions
  - v1.0
    index.html
    assets

What init asks

init sets the project up through five questions. Enter keeps the default, listed in the table below; an answer it does not understand is asked again.

$ npx docpensieve init my-site
Project name [My documentation]: Acme docs
Public URL of the site (optional): https://acme.github.io/docs
First version [1.0]:

CSS framework:
  1. tailwind — Tailwind CSS — ships with the tool, nothing to install
  2. custom — custom theme, light stylesheet, your own classes in theme/
Your choice [1-2]: 2
Install DocPensieve's documentation in the site? [Y/n]:

Question	Default	What your answer changes	Answered in advance by
Project name	`My documentation`	The name in the header, in the page titles and in the structured data.	`--name`
Public URL of the site	none	The canonical links and the structured data. Its path becomes the deployment prefix: `https://acme.github.io/docs` serves the site under `/docs/`. Leave it empty until you know.	`--site-url`
First version	`1.0`	The folder of your pages, `docs/v1.0/`, and the version in the URLs. `1.0` and `v1.0` are the same answer.	`--version-name`
CSS framework	`tailwind`	`tailwind` compiles the utilities your pages use, with nothing more to install. `custom` is a plain stylesheet: your own classes go in a `theme/` folder. Type the number or the name.	`--theme`
DocPensieve's documentation	yes	Yes: this documentation joins your menu, in a DocPensieve section matching your version. No: the site starts with your pages alone.	`--minimal`, for no

What it writes, depending on your answers

File	Written when
`docpensieve.config.mjs`	always — every option, each with a comment
`docs/v1.0/index.md` and `docs/v1.0/01-guide/01-installation.md`	always — a home page and a first page
`.gitignore`	always — the output folder is added to it
`docs/v1.0/99-docpensieve/`	documentation: yes — delete it when you are done
`theme/custom.css`	theme: `custom` — where your own classes go
`theme/99-docpensieve.css`	theme: `custom` and documentation: yes — the classes of its examples

The answers end up in docpensieve.config.mjs: the name, the URL and the theme can be changed there later.

In a script or in continuous integration, --yes accepts every default and the options answer the rest:

npx docpensieve init my-site --yes --name "Acme docs" --theme custom --minimal

Where the terminal cannot take answers, init says so, then keeps to the options and the defaults.

What it costs the reader

JavaScript

Hydration

100%

HTML served as is

100%

One stylesheet per version

Two dials at zero, and that is on purpose: React serves the build, not the display. What reaches the reader is markup and a stylesheet.

What sets the tool apart

Nothing to load

No hydration, no bundle to download before reading. A page stays readable in ten years, because there is nothing that can stop working.

One version per branch

Each published version lives on its own orphan branch, with its history. Going back to an old version does not require rebuilding it.

The frontmatter is enough

Title, description, authors and dates produce the JSON-LD, the breadcrumb and the metadata. Nothing to write twice.

Nothing fails silently

An unknown value, a missing parent, a dead link: each one stops the build with a message and a hint.

Quality, in figures

These gauges are not decorative: they are the repository's own measurements, taken by hand — nothing updates them on its own. Coverage and typing are checked on every push.

What is not measured does not improve — and what is not checked every time degrades.

Line coverage97%

Branch coverage87%

Typing of code and tests100%

A page, end to end

---
title: Installation
description: Install the tool.
---

# Installation

Node.js 22 or later.

<Tooltip text="Complete new project">init</Tooltip>
sets up the configuration.

The file is read, its frontmatter detached, its content compiled to HTML. Components are rendered at build time: Tooltip becomes two elements and a style rule, without a line of script.

The title feeds the <title> tag, the description the metadata, and both together the JSON-LD. The file name gives the URL, its folder the place in the menu.

None of this needs configuration: writing a page is enough.