Skip to content
DocPensieve

DocPensieve — Documentation & Magical Memory

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 See an example

Guide

From installation to deployment, in order.

Components

Fifteen components usable without an import, and what they load, you choose.

Reference

Commands, configuration, frontmatter and theme.

Architecture

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

New in this beta

  • A banner for the head of a page — Hero, with its row of ways in.
  • A calendar — the days your events fall on, navigable once loaded.
  • A button that copies a block of code — copyCode, off by default: a page loads only what it uses.
  • A code block that names a file — Snippet reads a real file of your project at generation, so an example cannot go stale.
  • init asks about languages — one question, and the project comes out with its second language wired: the folder, the configuration field and a page to start from.
  • Pages a program can read — llms: true writes llms.txt and a Markdown copy of each page.
  • A strict Content-Security-Policy — the two inline scripts are allowed by their hash, and the deployment guide gives the policy.

Everything that is new · Migrate from latest to beta

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 buildTurning the sources into HTML pages ready to serve. 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 six 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]:
Will the site be in several languages? [y/N]: y
Code of the second language [fr]:

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]:
QuestionDefaultWhat your answer changesAnswered in advance by
Project nameMy documentationThe name in the header, in the page titles and in the structured data.--name
Public URL of the sitenoneThe 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 version1.0The folder of your pages, docs/v1.0/, and the version in the URLs. 1.0 and v1.0 are the same answer.--version-name
A second languagenoYes, then a code: your pages get a folder of their own in that language — docs/v1.0-fr/, served under /fr/. A page with no twin in it does not exist in that language.--translation fr
CSS frameworktailwindtailwind 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 documentationyesYes: 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

FileWritten when
docpensieve.config.mjsalways — every option, each with a comment
docs/v1.0/index.md and docs/v1.0/01-guide/01-installation.mdalways — a home page and a first page
docs/v1.0-fr/index.mda second language — the home page, ready to translate
.gitignorealways — the output folder is added to it
docs/v1.0/99-docpensieve/documentation: yes — delete it when you are done
theme/custom.csstheme: custom — where your own classes go
theme/99-docpensieve.csstheme: 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

0%
JavaScript runtime
0%
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 — and, on this site, the light / dark switch and the button that copies a block of code: about two kilobytes, on the pages that have code, and nowhere else.

That is the promise, and it is the one to hold: not that a page loads nothing, but that it loads only what it uses.

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. CoverageShare of lines executed by the test suite. and typingTypeScript checks the JSDoc of the source code and of the tests. 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.