Pour qui

La doc technique avec le code intact

Clean Clipper lit le langage sur la page elle-même – la classe du bloc, l’élément parent, le balisage laissé par la coloration du site – et l’inscrit sur la clôture. Sur un corpus technique de neuf pages, l’étiquette a survécu dans 73 blocs sur 156, contre 20 et 0 pour les deux autres moteurs mesurés. Le reste de la page arrive en Markdown standard, sans la barre latérale.

Ce qui casse à la copie

Une documentation, c’est d’abord du code, et c’est exactement la partie que la plupart des clippers abîment. Le bloc arrive nu, sans étiquette : dans Obsidian il s’affiche en gris uniforme, dans un dépôt il traverse la revue sans coloration. Vous rouvrez donc chaque note pour retaper js, python ou bash au-dessus de chaque clôture. Sur une documentation de trente pages, c’est une soirée passée à réparer ce qui existait déjà sur la page d’origine.

Le reste de la capture ne vaut guère mieux. Le sélecteur de version, la barre latérale et le fil « Sur cette page » atterrissent au milieu du texte, et un tableau de paramètres s’effondre sur une seule ligne parce qu’une cellule contenait un exemple de code. Trois mois plus tard, vous cherchez une option d’API dans vos notes et vous tombez d’abord sur trois copies du menu. La note existe, mais elle ne se relit pas.

Reste la question de la version, celle qui coûte le plus cher à découvrir tard. Une note de documentation sans son adresse ne dit pas si elle décrit la branche stable ou la préversion, et les deux pages portent le même titre, souvent au mot près. Le segment de version vit dans l’URL, pas dans le texte ; s’il ne voyage pas avec la note, vous corrigez un jour un bogue en suivant la doc d’une version que votre projet n’utilise pas. Ici, l’adresse complète part dans le champ source du frontmatter, segment de version compris.

Ce qui change dans la note

• Le bloc ressort en ```js et non nu – la coloration fonctionne dans Obsidian, VS Code et GitHub dès le collage
• Le langage est lu sur la page – attributs data-lang et data-language, classes language-*, lang-* et hljs-* – jamais deviné à partir du code
• Les alias sont ramenés à une forme unique : javascript devient js, typescript devient ts, yml devient yaml
• Un tableau de paramètres dont une cellule contient du code garde ses lignes au lieu de s’aplatir
• Les liens relatifs deviennent des adresses absolues avant la conversion : plus de ../api/ mort dans la note
• Les liens de renvoi deviennent des notes [^1], avec leurs définitions rassemblées en fin de fichier
• Barre latérale, sélecteur de version et fil « Sur cette page » sont coupés, pas convertis
• Le code en ligne reste du code en ligne, y compris dans les titres et les cellules

## Enchaîner les promesses

La méthode `fetch()` renvoie une promesse que l’on enchaîne :

```js
fetch("/api/produits")
  .then((reponse) => reponse.json())
  .then((donnees) => console.log(donnees));
```

| Méthode | Ce qu’elle renvoie |
| --- | --- |
| `then()` | une nouvelle promesse |
| `catch()` | une promesse, en cas de rejet |

Régler l’extension pour une documentation

Sept réglages, faits une fois, après quoi une page de doc devient un fichier rangé sans aucune manipulation. Chaque étape se vérifie à l’écran : soit le réglage est en place, soit il ne l’est pas.

1. Épinglez l’icône : cliquez sur la pièce de puzzle à droite de la barre d’adresse, puis sur l’épingle en face de Clean Clipper. Sans cela, il faut rouvrir ce menu à chaque capture, et le raccourci Alt+Shift+M reste le seul chemin rapide.
2. Ouvrez les paramètres depuis la fenêtre de l’extension. Dans « Clic sur l’icône », gardez « Ouvrir la fenêtre » tant que vous n’avez pas confiance dans le résultat : sur une documentation, la clôture de code et les tableaux méritent un coup d’œil avant l’écriture du fichier.
3. Dans « Où enregistrer », appuyez sur « Choisir… » en face de « Dossier sur le disque » et désignez le dossier de notes de votre projet. Le navigateur demande l’autorisation une seule fois et la retient ; si elle est révoquée, l’extension affiche « accès non accordé, choisissez à nouveau » au lieu d’échouer en silence.
4. Remplacez le modèle « Nom du fichier » par {domain} - {title}. Deux documentations ont toutes les deux une page « Installation » ; sans le domaine dans le nom, la seconde capture arriverait sous Installation-2.md, et vous ne sauriez plus laquelle est laquelle.
5. Dans « Ce qui entre dans la note », passez « Images » sur « ignorer » et laissez cochées « Renvoyer les notes de bas de page à la fin » et « Couper la navigation, la pagination et les blocs de service ». Les schémas d’une doc ne sont de toute façon que des liens vers le site d’origine.
6. Ouvrez « Boutons de la fenêtre » et activez « Dossier ». À l’installation, seuls « Copier » et « En .md » sont affichés – sans cette case, l’écriture dans le dossier choisi n’a aucun bouton pour la déclencher.
7. Vérifiez sur une vraie page : ouvrez une page de référence, tapez Alt+Shift+M, et regardez la première clôture. Si elle porte ```js et que le tableau des paramètres a gardé ses lignes, le réglage est bon et vous pouvez basculer « Clic sur l’icône » sur « Placer dans un dossier ».

Réglages conseillés pour la doc

Ce tableau vaut pour la documentation d’API et les références de langage. Les valeurs ne sont pas celles de l’installation par défaut : trois d’entre elles doivent être changées à la main.

## Exemple

Dans cet extrait, un téléchargement lancé avec `fetch()` est interrompu.

```
const controleur = new AbortController();
const signal = controleur.signal;

document
  .querySelector(".annuler")
  .addEventListener("click", () => controleur.abort());
```

| Membre | Type | Ce qu’il fait |
| --- | --- | --- |
| `AbortController.signal` | `AbortSignal` | renvoie le signal lié au contrôleur |
| `AbortController.abort()` | – | accepte un argument `raison` facultatif |

Trois usages réels

Reprendre une API dans le README du projet

Vous intégrez une bibliothèque et le README doit montrer l’appel minimal. Sur la page de référence, vous sélectionnez la section « Exemples », vous tapez Alt+Shift+M, et le Markdown est dans le presse-papiers avec le bloc déjà étiqueté. Le collage dans le README donne une coloration correcte du premier coup, sans retaper la clôture.

Attention à un effet de bord utile à connaître : quand la capture part d’une sélection, la coupe de l’habillage est désactivée, parce que ce que vous avez sélectionné à la main n’a pas à être filtré. Si votre sélection a débordé sur la barre latérale, celle-ci arrive avec. Sélectionnez à partir du titre de la section, pas depuis la marge.

Garder la doc d’une version avant qu’elle disparaisse

Une majeure sort, l’éditeur annonce que la documentation de la version précédente sera retirée dans six mois, et votre service tourne encore dessus. Vous parcourez les pages qui vous concernent, une par une, avec le modèle de nom {domain} - {title} et un sous-dossier au nom de la version. Chaque fichier garde dans son champ source l’adresse complète, segment de version inclus.

Le jour où l’ancienne doc est débranchée, le dossier reste lisible hors ligne et cherchable en texte intégral. Ce que vous n’avez pas : les images, qui étaient des liens vers un site qui ne les sert plus, et les liens internes de la doc, restés absolus et devenus morts. Le texte et le code, eux, sont là.

Capturer une documentation interne derrière une connexion

Le wiki de l’équipe demande une authentification d’entreprise, ce qui met hors jeu tout outil qui va chercher la page depuis un serveur. Ici, l’extraction lit la page que votre navigateur a déjà affichée pour vous, après connexion : si la page est à l’écran, elle se capture, et rien ne sort de la machine puisque l’extension ne fait aucune requête réseau.

C’est aussi le cas où la capture d’une page rendue en JavaScript se comporte bien : le DOM est lu une fois la page affichée, donc la section réellement ouverte dans l’accordéon est celle qui part dans le fichier. Refermez la section avant de capturer et elle manquera – l’extension n’enregistre que ce qui existe à l’écran.

Comparé aux façons de faire actuelles

Une documentation finit toujours par être recopiée quelque part. Voici les chemins habituels, ce qu’ils donnent vraiment, et ce qu’ils coûtent – la dernière ligne comprise.

Quand ça ne sort pas comme prévu

Pourquoi ce bloc de code est-il sorti sans étiquette ?

Parce que la page ne dit nulle part de quel langage il s’agit. L’extension regarde les attributs data-lang, data-language, lang et data-code-language sur le bloc, son parent et son grand-parent, puis les classes de coloration ; si rien n’y figure, la clôture reste nue. Deviner le langage à partir du code produirait une étiquette fausse un bloc sur cinq, et une étiquette fausse coûte plus cher qu’une étiquette absente.

Deux autres cas donnent le même résultat sans qu’il y ait de défaut : la page déclare plaintext, text ou none, qui sont traités comme une absence d’étiquette, et le langage déclaré ne fait pas partie de la soixantaine reconnue. Un dialecte maison ou un pseudo-langage propre à un éditeur tombe dans ce second cas.

Pourquoi la page est-elle arrivée vide ou coupée en plein milieu ?

Presque toujours parce que la partie manquante n’était pas affichée au moment du clic. Les documentations modernes replient les sections dans des accordéons et chargent les exemples à la demande : ce qui est replié n’est pas dans le DOM, donc pas dans la capture. Dépliez la section, laissez la page finir de s’afficher, puis capturez.

Si le corps de l’article ne s’affiche jamais mais que la page le publie dans ses données structurées, l’extension bascule dessus et l’écrit dans la note : le champ extraction porte alors jsonld-articlebody au lieu de dom. Ce champ est là précisément pour que vous sachiez d’où vient le texte sans avoir à le deviner.

Pourquoi la barre latérale est-elle restée dans ma note ?

Parce que la capture est partie d’une sélection. Sur une sélection, la coupe de l’habillage est volontairement désactivée : vous avez désigné ce texte à la main, et retirer des morceaux de ce que quelqu’un a sélectionné exprès serait la pire des surprises. Le sélecteur en haut de la fenêtre indique toujours si vous regardez « Page entière » ou « Sélection ».

La correction tient en un geste : cliquez sur « Page entière » dans la fenêtre, ou décochez « Si du texte est sélectionné, n’enregistrer que la sélection » dans les paramètres quand vous enchaînez des captures de pages entières.

Pourquoi le nom du fichier est-il rempli de tirets ?

Parce que le titre de la page contient des caractères qu’un système de fichiers refuse. Tout ce qui n’est ni une lettre, ni un chiffre, ni un espace, ni l’un de . , ( ) _ - est remplacé par un tiret, et le nom est coupé à 90 caractères. Un titre comme Array.prototype.map() : JavaScript | MDN donne donc une suite de tirets là où se trouvaient les deux-points et la barre verticale.

Si ces noms vous gênent, mettez {domain} - {title} de côté et utilisez {domain} {date} pour les pages dont le titre est bavard. Le titre exact reste de toute façon écrit en clair dans le champ title du frontmatter, donc rien n’est perdu.

Ce qu’il ne fait pas

Il ne devine pas le langage d’un bloc que la page n’étiquette pas : là où le site rend du code sans classe, la clôture reste nue, et c’est délibéré – une étiquette inventée coûte plus cher qu’une étiquette absente. Il n’explore pas un site de documentation entier : une page à la fois, celle que vous regardez, sans robot et sans traitement par lots. Il ne télécharge ni schémas ni captures d’écran, les images restent des liens vers le site d’origine. Et sur les pages que le navigateur protège, comme chrome:// et la boutique d’extensions, il ne s’exécute pas du tout.

Questions