DocPensieve
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.
Nouveautés de la 0.4
- Un menu qui se replie —
foldedSidebar, et le menu de la documentation replié au-dessus du contenu sur écran étroit. - Un panneau de liens dans l'en-tête — une entrée
headerLinksà colonnes. - Un composant de menu —
Menu, posé n'importe où dans une page, replié sur mobile. - Des admonitions — six types livrés, et les vôtres déclarés dans la configuration.
- Un en-tête collant ou non —
stickyHeader, pour rendre sa hauteur au texte. - Des icônes issues d'un jeu —
simple-icons:github, intégrées à la génération comme vos propres fichiers. - Un site en plusieurs langues — une traduction par version, servie sous son code, avec la coquille dans cette langue.
Toutes les nouveautés · Migrer de la 0.3 vers la 0.4
En trois commandes
npx docpensieve init mon-site
cd mon-site
npx docpensieve devLa 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érationTransformer les sources en pages HTML prêtes à servir. tourne sur votre machine, et le site produit ne demande qu'un hébergeur de fichiers.
dist
- index.html
- versions.json
versions
v1.0
- index.html
- assets
Ce que demande init
init met le projet en place en cinq 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]:
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 |
| 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 |
.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 --minimalLà 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
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, les quelques lignes de son bouton clair / sombre.
Ce qui distingue l'outil
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.
Chaque version publiée vit sur sa branche orpheline, avec son historique. Revenir à une ancienne version ne demande pas de la regénérer.
Titre, description, auteurs et dates produisent le JSON-LD, le fil d'Ariane et les métadonnées. Rien à écrire deux fois.
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 couverturePart des lignes exécutées par la suite de tests. et le typageTypeScript vérifie les JSDoc du code source et des tests. 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.
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.