DocPensieve

Vos fichiers Markdown et MDX deviennent un site statique. Aucun runtime à charger, une version par branche, des données structurées déduites du frontmatter.

Commencer Voir les composants Voir un exemple

Guide

De l'installation au déploiement, dans l'ordre.

Composants

Quinze composants utilisables sans import, et ce qu'ils chargent, vous le choisissez.

Référence

Commandes, configuration, frontmatter et thème.

Architecture

Comment une page devient du HTML, et pourquoi ainsi.

Nouveautés de cette bêta

Un bandeau pour la tête d'une page — Hero, avec sa rangée d'entrées.
Un calendrier — les jours où tombent vos événements, navigable une fois chargé.
Un bouton qui copie un bloc de code — copyCode, éteint par défaut : une page ne charge que ce qu'elle emploie.
Un bloc de code qui désigne un fichier — Snippet lit un vrai fichier de votre projet à la génération : un exemple ne peut plus se périmer.
init demande la langue — une question, et le projet sort avec sa seconde langue câblée : le dossier, le champ de configuration et une page pour démarrer.
Des pages qu'un programme sait lire — llms: true écrit llms.txt et une copie Markdown de chaque page.
Une Content-Security-Policy stricte — les deux scripts en ligne sont autorisés par leur empreinte, et le guide de déploiement donne la politique.

Toutes les nouveautés · Migrer de latest vers la bêta

En trois commandes

npx docpensieve init mon-site
cd mon-site
npx docpensieve dev

La première pose quelques questions — détaillées plus bas — puis écrit une configuration et un dossier de documentation ; la dernière ouvre un serveur qui régénère à chaque enregistrement.

Rien d'autre à installer : la génération tourne sur votre machine, et le site produit ne demande qu'un hébergeur de fichiers.

Ce que vous obtenez

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

Ce que demande init

init met le projet en place en six questions. Entrée garde la valeur par défaut, indiquée dans le tableau ; une réponse qu'il ne comprend pas est reposée.

$ npx docpensieve init mon-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]:

Question	Défaut	Ce que votre réponse change	Répondu à l'avance par
Nom du projet	`My documentation`	Le nom dans l'en-tête, dans les titres de page et dans les données structurées.	`--name`
Adresse publique du site	aucune	Les liens canoniques et les données structurées. Son chemin devient le préfixe de déploiement : `https://acme.github.io/docs` sert le site sous `/docs/`. À laisser vide si besoin.	`--site-url`
Première version	`1.0`	Le dossier de vos pages, `docs/v1.0/`, et la version dans les adresses. `1.0` et `v1.0` sont la même réponse.	`--version-name`
Une seconde langue	non	Oui, puis un code : vos pages reçoivent un dossier à elles dans cette langue — `docs/v1.0-fr/`, servi sous `/fr/`. Une page sans jumelle dedans n'existe pas dans cette langue.	`--translation fr`
Framework CSS	`tailwind`	`tailwind` compile les utilitaires employés par vos pages, sans rien de plus à installer. `custom` est une feuille simple : vos classes vivent dans un dossier `theme/`.	`--theme`
Documentation de DocPensieve	oui	Oui : cette documentation rejoint votre menu, dans une section DocPensieve correspondant à votre version. Non : le site démarre avec vos seules pages.	`--minimal`, pour non

Ce qu'il écrit, selon vos réponses

Fichier	Écrit quand
`docpensieve.config.mjs`	toujours — toutes les options, chacune commentée
`docs/v1.0/index.md` et `docs/v1.0/01-guide/01-installation.md`	toujours — une page d'accueil et une première page
`docs/v1.0-fr/index.md`	une seconde langue — la page d'accueil, prête à traduire
`.gitignore`	toujours — le dossier de sortie y est ajouté
`docs/v1.0/99-docpensieve/`	documentation : oui — à supprimer quand vous n'en avez plus besoin
`theme/custom.css`	thème : `custom` — là où vont vos propres classes
`theme/99-docpensieve.css`	thème : `custom` et documentation : oui — les classes de ses exemples

Les réponses atterrissent dans docpensieve.config.mjs : le nom, l'adresse et le thème s'y changent ensuite.

Dans un script ou en intégration continue, --yes accepte tous les défauts et les options répondent au reste :

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

Là où le terminal ne peut pas recueillir de réponses, init le dit, puis s'en tient aux options et aux défauts.

Ce que cela coûte au lecteur

Runtime JavaScript

Hydratation

100%

HTML servi tel quel

100%

Une feuille par version

Deux cadrans à zéro, et c'est voulu : React sert à la génération, pas à l'affichage. Ce qui parvient au lecteur, c'est du balisage et une feuille de style — et, sur ce site, le bouton clair / sombre et celui qui copie un bloc de code : deux kilooctets environ, sur les pages qui ont du code, et nulle part ailleurs.

C'est là la promesse, et c'est elle qu'il faut tenir : non pas qu'une page ne charge rien, mais qu'elle ne charge que ce qu'elle emploie.

Ce qui distingue l'outil

Rien à charger

Aucune hydratation, aucun paquet à télécharger avant de lire. Une page reste lisible dans dix ans, parce que rien ne peut cesser de fonctionner.

Une version par branche

Chaque version publiée vit sur sa branche orpheline, avec son historique. Revenir à une ancienne version ne demande pas de la regénérer.

Le frontmatter suffit

Titre, description, auteurs et dates produisent le JSON-LD, le fil d'Ariane et les métadonnées. Rien à écrire deux fois.

Rien n'échoue en silence

Une valeur inconnue, un parent manquant, un lien mort : chacun arrête la génération avec un message et une piste.

La qualité, en chiffres

Ces jauges ne décorent pas : ce sont les mesures du dépôt, relevées à la main — rien ne les met à jour tout seul. La couverture et le typage sont contrôlés à chaque poussée.

Ce qui ne se mesure pas ne s'améliore pas — et ce qui ne se vérifie pas à chaque fois se dégrade.

Couverture des lignes97%

Couverture des branches87%

Typage du code et des tests100%

Une page, de bout en bout

---
title: Installation
description: Installer l'outil.
---

# Installation

Node.js 22 ou plus récent.

<Tooltip text="Crée un projet complet">init</Tooltip>
met la configuration en place.

Le fichier est lu, son frontmatter détaché, son contenu compilé en HTML. Les composants sont rendus à la génération : Tooltip devient deux éléments et une règle de style, sans une ligne de script.

Le titre alimente la balise <title>, la description les métadonnées, et les deux ensemble le JSON-LD. Le nom du fichier donne l'adresse, son dossier la place dans le menu.

Rien de tout cela ne demande de configuration : écrire une page suffit.