# DocPensieve

> Générateur de site de documentation statique — Markdown et MDX en entrée, HTML sans runtime en sortie, une version par branche.

<div className="dp-hero">

<div className="inline-block w-80 max-w-full mb-2">

![DocPensieve — Documentation & Magical Memory](/versions/beta/fr/icons/logo.jpg)

</div>

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

<div className="dp-actions">

[Commencer](/versions/beta/fr/guide/installation/) [Voir les composants](/versions/beta/fr/components/) [Voir un exemple](/versions/beta/fr/examples/)

</div>

</div>

<Columns>
  <Column>
    <Card className="h-full" href="/versions/beta/fr/guide/">
      <CardBody className="text-sm text-slate-600 dark:text-slate-400">
        <LogoIcon src="/versions/beta/fr/icons/compass.svg" size="1.75rem" style={{ color: 'var(--dp-accent)' }} />
        <strong className="block mt-3 mb-1 text-base font-semibold">Guide</strong>

        De l'installation au déploiement, dans l'ordre.
      </CardBody>
    </Card>

  </Column>
  <Column>
    <Card className="h-full" href="/versions/beta/fr/components/">
      <CardBody className="text-sm text-slate-600 dark:text-slate-400">
        <LogoIcon src="/versions/beta/fr/icons/blocks.svg" size="1.75rem" style={{ color: 'var(--dp-accent)' }} />
        <strong className="block mt-3 mb-1 text-base font-semibold">Composants</strong>

        Quinze composants utilisables sans import, et ce qu'ils chargent, vous le choisissez.
      </CardBody>
    </Card>

  </Column>
  <Column>
    <Card className="h-full" href="/versions/beta/fr/reference/">
      <CardBody className="text-sm text-slate-600 dark:text-slate-400">
        <LogoIcon src="/versions/beta/fr/icons/list.svg" size="1.75rem" style={{ color: 'var(--dp-accent)' }} />
        <strong className="block mt-3 mb-1 text-base font-semibold">Référence</strong>

        Commandes, configuration, frontmatter et thème.
      </CardBody>
    </Card>

  </Column>
  <Column>
    <Card className="h-full" href="/versions/beta/fr/architecture/">
      <CardBody className="text-sm text-slate-600 dark:text-slate-400">
        <LogoIcon src="/versions/beta/fr/icons/branch.svg" size="1.75rem" style={{ color: 'var(--dp-accent)' }} />
        <strong className="block mt-3 mb-1 text-base font-semibold">Architecture</strong>

        Comment une page devient du HTML, et pourquoi ainsi.
      </CardBody>
    </Card>

  </Column>
</Columns>

## 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](/versions/beta/fr/whats-new/) ·
[Migrer de latest vers la bêta](/versions/beta/fr/guide/migrate-to-beta/)

## En trois commandes

<Columns>
  <Column span={7}>

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

La première pose quelques questions — [détaillées plus bas](#ce-que-demande-init) —
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 <Tooltip text="Transformer les sources en pages HTML prêtes à servir.">génération</Tooltip> tourne sur votre machine, et le site produit ne demande qu'un hébergeur de fichiers.

  </Column>
  <Column span={5}>
    <Card className="h-full">
      <CardHeader>Ce que vous obtenez</CardHeader>
      <CardBody>
        <Tree>
          <TreeItem label="dist" open>
            <TreeItem label="index.html" />
            <TreeItem label="versions.json" />
            <TreeItem label="versions" open>
              <TreeItem label="v1.0">
                <TreeItem label="index.html" />
                <TreeItem label="assets" />
              </TreeItem>
            </TreeItem>
          </TreeItem>
        </Tree>
      </CardBody>
    </Card>
  </Column>
</Columns>

## 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 :

```bash
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

<div className="flex flex-wrap justify-center gap-6 my-8">
  <Skill
    name="Runtime JavaScript"
    level={0}
    shape="circle"
    color="#10b981"
    icon={<LogoIcon src="/versions/beta/fr/icons/lightning.svg" />}
  />
  <Skill
    name="Hydratation"
    level={0}
    shape="circle"
    color="#10b981"
    icon={<LogoIcon src="/versions/beta/fr/icons/lightning.svg" />}
  />
  <Skill
    name="HTML servi tel quel"
    level={100}
    shape="circle"
    color="var(--dp-accent)"
    icon={<LogoIcon src="/versions/beta/fr/icons/shield.svg" />}
  />
  <Skill
    name="Une feuille par version"
    level={100}
    shape="circle"
    color="var(--dp-accent)"
    icon={<LogoIcon src="/versions/beta/fr/icons/book.svg" />}
  />
</div>

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

<Columns>
  <Column span={6}>
    <Card className="h-full">
      <CardHeader>Rien à charger</CardHeader>
      <CardBody className="text-sm">
        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.
      </CardBody>
    </Card>
  </Column>
  <Column span={6}>
    <Card className="h-full">
      <CardHeader>Une version par branche</CardHeader>
      <CardBody className="text-sm">
        Chaque version publiée vit sur sa branche orpheline, avec son historique. Revenir à une
        ancienne version ne demande pas de la regénérer.
      </CardBody>
    </Card>
  </Column>
  <Column span={6}>
    <Card className="h-full">
      <CardHeader>Le frontmatter suffit</CardHeader>
      <CardBody className="text-sm">
        Titre, description, auteurs et dates produisent le JSON-LD, le fil d'Ariane et les
        métadonnées. Rien à écrire deux fois.
      </CardBody>
    </Card>
  </Column>
  <Column span={6}>
    <Card className="h-full">
      <CardHeader>Rien n'échoue en silence</CardHeader>
      <CardBody className="text-sm">
        Une valeur inconnue, un parent manquant, un lien mort : chacun arrête la génération avec un
        message et une piste.
      </CardBody>
    </Card>
  </Column>
</Columns>

## La qualité, en chiffres

<Columns>
  <Column span={7}>

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 <Tooltip text="Part des lignes exécutées par la suite de tests.">couverture</Tooltip> et le <Tooltip text="TypeScript vérifie les JSDoc du code source et des tests.">typage</Tooltip> 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.

  </Column>
  <Column span={5}>
    <Skill name="Couverture des lignes" level={97} color="#10b981" icon={<LogoIcon src="/versions/beta/fr/icons/shield.svg" />} />
    <Skill name="Couverture des branches" level={87} color="#f59e0b" icon={<LogoIcon src="/versions/beta/fr/icons/shield.svg" />} />
    <Skill name="Typage du code et des tests" level={100} color="var(--dp-accent)" icon={<LogoIcon src="/versions/beta/fr/icons/star.svg" />} />
  </Column>
</Columns>

## Une page, de bout en bout

<Columns>
  <Column span={5}>

```mdx
---
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.
```

  </Column>
  <Column span={7}>

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](/versions/beta/fr/guide/writing-pages/)
suffit.

  </Column>
</Columns>