Rédacteur de tutoriel HackMD

Aperçu

Ce skill recherche un sujet donné (outil, bibliothèque, framework, API, ou tout logiciel) et rédige un tutoriel structuré au format HackMD Markdown, prêt à être utilisé dans une note HackMD. Il se distingue par trois caractéristiques principales :

Rechercher d'abord, écrire ensuite — ne jamais se fier uniquement à sa mémoire.
Destiné aux débutants — explications simples et exemples courts pour que le lecteur apprenne vraiment à utiliser le sujet.
Respect strict d'un format de titres numérotés et de blocs que HackMD peut interpréter correctement, afin d'avoir un panneau de plan/sommaire qui fonctionne. Tout le contenu produit est rédigé en chinois traditionnel (usage taïwanais). Même si l'utilisateur donne des instructions dans une autre langue, l'article lui-même (titres, corps du texte, descriptions d'exemples) doit être en chinois traditionnel ; seuls le code (noms de variables, commandes, syntaxe) restent dans leur langue d'origine.

Public et profondeur

Par défaut : Débutant

Sauf demande contraire de l'utilisateur, l'article est destiné à un public n'ayant aucune expérience en programmation :

Seulement expliquer l'utilisation réelle du sujet, sans chercher à être exhaustif.
Les exemples doivent être les plus simples, les plus courts et directement exécutables, juste assez pour illustrer la fonctionnalité décrite dans le paragraphe.
Pour les termes techniques, expliquer en une phrase simple la première fois (ex : « Gestionnaire de paquets : un petit outil qui télécharge et installe des programmes »).
Chaque étape doit être accompagnée d'une explication de ce que l'utilisateur verra après l'avoir exécutée, pour qu'il puisse vérifier qu'il a bien fait.
La longueur dépend du sujet, généralement entre 1500 et 3000 caractères. Mieux vaut court et clair que long et inutile.
Les sections comme « Configuration avancée » ou « Comparaison avec des alternatives » ne sont pas incluses par défaut.

Alternatif : Version avancée et approfondie

Uniquement si l'utilisateur demande explicitement du contenu « approfondi », « avancé », « complet » ou « destiné aux développeurs expérimentés » :

La longueur peut dépasser 3000 caractères, et il faut expliquer pourquoi les choses fonctionnent ainsi, et pas seulement quoi fait la syntaxe.
On peut ajouter des sections comme configuration avancée, cas limites, considérations de performance, comparaison avec des alternatives.

Choix de la pile technique

Ne pas utiliser la pile technique par défaut des préférences utilisateur (par exemple ASP.NET Core MVC, C#, SQL Server) à moins que le sujet de l'article ne soit précisément cette technologie. Les exemples doivent utiliser le langage et l'environnement les plus courants et les plus adaptés aux débutants, selon la documentation officielle du sujet.

Flux de travail

Étape 1 : Clarifier le sujet et l'angle (uniquement si vraiment ambigu)

Si le sujet donné par l'utilisateur est déjà suffisamment spécifique, on peut commencer directement (ex : « Écris-moi un tutoriel sur Vite », « write a tutorial on FastAPI dependency injection »), sans poser de questions, et passer à la phase de recherche.

Ne demander à l'utilisateur que dans les deux cas suivants :

Le nom du sujet peut correspondre à plusieurs choses différentes (ex : « Mongo » pourrait être la base de données MongoDB ou autre chose).
Le périmètre n'est pas clair au point d'affecter la direction de l'article (ex : « React » fait-il référence à une introduction générale ou à une fonctionnalité spécifique ?).

Étape 2 : Rechercher en profondeur avant d'écrire

C'est l'étape la plus importante. Ne pas écrire de mémoire puis « vérifier après coup » ; il faut d'abord rechercher, puis écrire.

Considérer la documentation officielle / le site officiel et les tutoriels de qualité comme des sources fiables. La documentation officielle est la meilleure source pour obtenir la liste précise des fonctionnalités, les étapes d'installation et les détails de l'API ; les tutoriels indépendants et les blogs sont plus adaptés pour obtenir des exemples d'utilisation concrets, des pièges courants et des cas d'utilisation réels souvent omis par la documentation officielle.
Ajuster le nombre de recherches en fonction de l'ampleur du sujet : pour un sujet ciblé (un seul outil CLI, une seule fonctionnalité de bibliothèque), environ 4 à 6 recherches ; pour un sujet plus large (un framework entier), environ 8 à 15 recherches ou plus, couvrant différents aspects (installation, concepts de base, configuration, cas d'utilisation courants, changements récents de version).
Toujours vérifier la version la plus récente. Rechercher des mots-clés comme « release notes », « changelog », « version », « what's new » pour s'assurer que les commandes d'installation et les descriptions des fonctionnalités reflètent l'état actuel, et non des souvenirs obsolètes.
Utiliser un outil de capture de page Web pour lire le contenu complet des pages les plus pertinentes (guide officiel de démarrage, page d'installation, tutoriel important), et ne pas se fier uniquement aux extraits des résultats de recherche, car ils sont généralement trop courts pour rédiger un contenu précis.
Respecter les droits d'auteur : ne jamais copier textuellement de longs passages d'une source. Tout le contenu doit être reformulé avec ses propres mots, en intégrant des informations provenant de plusieurs sources, et non en recopiant une seule source. Les exemples de code auto-écrits sont une pratique normale de rédaction technique et ne constituent pas une reproduction de contenu.
Noter les URL des sources réellement utilisées pendant la recherche, pour les lister dans la section des ressources supplémentaires à la fin de l'article.

Étape 3 : Déterminer la structure des sections en fonction du sujet

Pas de modèle fixe ; laisser la nature du sujet décider quelles sections sont pertinentes, et ne pas forcer des sections non pertinentes dans un squelette préétabli. Un article destiné aux débutants couvre généralement les parties suivantes :

Introduction : Qu'est-ce que c'est ? Pourquoi quelqu'un voudrait-il l'utiliser ? Utiliser une métaphore de la vie quotidienne pour expliquer.
Fonctionnalités / Caractéristiques : Ce qu'il peut réellement faire, se limiter à quelques-unes des plus utiles pour un débutant.
Installation / Configuration : Uniquement si l'installation est réellement pertinente (nécessaire pour un outil CLI ou une bibliothèque ; peut ne pas être nécessaire pour un produit SaaS ou un concept de langage de programmation).
Démarrage rapide : Un exemple minimal qui fonctionne, et expliquer ce que l'on verra après son exécution.
Exemples d'utilisation : Un ou deux exemples proches d'une utilisation réelle, mais toujours courts.
Questions fréquentes / Dépannage : Uniquement si la recherche a effectivement trouvé des erreurs ou problèmes courants. Ne pas inventer de toutes pièces ; si la recherche n'en trouve pas, omettre cette section.
Résumé et ressources supplémentaires : Conclusion, avec les liens vers la documentation officielle et les articles de référence utilisés pendant la recherche.

La version avancée peut ajouter des sections comme « Configuration avancée », « Comparaison avec des alternatives » (voir « Public et profondeur »).

Étape 4 : Rédiger l'article en utilisant le format de titres numérotés HackMD

Ce sont des règles de format strictes. HackMD utilise ces formats pour générer le panneau de plan/sommaire. Suivre ces règles à la lettre est bien plus important que l'apparence.

4-1 Début du fichier : Métadonnées YAML

HackMD utilise les métadonnées du fichier ou le premier titre comme nom de note. Pour éviter que chaque note s'appelle « 1. Introduction », on ajoute au tout début du fichier des métadonnées YAML, avec un titre et des tags :

---
title: Tutoriel d'introduction à Vite
tags: Vite, Frontend, Tutoriel
---

Après les métadonnées, une ligne vide, puis commencer directement par le premier titre 1\. Introduction. Ne pas ajouter # Titre de l'article ailleurs, pour éviter d'avoir un titre non numéroté dans le sommaire.

4-2 Quatre niveaux de titres

Niveau	Format de numérotation	Syntaxe Markdown	Remarques
1	`1\.`, `2\.`, `3\.` ...	Setext H1 : une ligne de texte, la ligne suivante `===`	Le point après le chiffre doit être échappé avec une barre oblique inverse, ex : `2\. Installation et configuration`
2	`1.1`, `1.2`, `2.1` ...	Setext H2 : une ligne de texte, la ligne suivante `---`	Pas besoin d'échappement, ex : `1.1 Méthode d'installation`
3	`1.1.1`, `1.1.2` ...	ATX H3 : `### 1.1.1 Texte`
4	`1.1.1.1`, `1.1.1.2` ...	ATX H4 : `#### 1.1.1.1 Texte`	Un chiffre de plus que le niveau précédent, facile à se tromper, vérifier chacun.

⚠️ Pourquoi le point du niveau 1 doit être échappé :

Si vous écrivez 2. Installation et configuration (sans échappement), Markdown interprète cette ligne comme un « élément de liste ordonnée », et le === de la ligne suivante ne forme pas un titre Setext ; tout le titre devient un format incorrect. En écrivant 2\. Installation et configuration, HackMD enlève la barre oblique inversée lors du rendu, le lecteur voit toujours « 2. Installation et configuration », mais le titre est correctement interprété.

Le niveau 2 (1.1) n'est pas au format « chiffre + point + espace », donc il n'est pas confondu avec une liste, et n'a pas besoin d'échappement.

2. Installation et configuration        ← Erreur : interprété comme un élément de liste, === invalide
===

2\. Installation et configuration       ← Correct : point échappé, titre Setext correctement interprété
===

4-3 Règles sur les lignes vides

Le texte du titre et la ligne de soulignement (=== ou ---) doivent être sur deux lignes consécutives, sans ligne vide entre elles, sinon Markdown les traite comme deux blocs distincts.
Après la ligne de soulignement, il faut une ligne vide avant de commencer le paragraphe suivant, un autre titre ou une ligne de séparation.

4-4 Règles sur les lignes de séparation

Pour une séparation visuelle claire entre les sections, ajouter une ligne de séparation horizontale --- autonome au-dessus de certains titres :

Titre	Quand ajouter une ligne de séparation
Niveau 1 (`1\.`)	Toujours. Exception unique : le premier titre du document (juste après les métadonnées YAML) n'en a pas besoin.
Niveau 2 (`1.1`)	Si juste au-dessus (en ignorant les lignes vides) il y a directement le `===` du niveau 1, ne pas en mettre ; si juste au-dessus il y a du texte, un bloc de code, une boîte d'info ou autre contenu, en mettre une.
Niveaux 3 et 4 (`###`, `####`)	Jamais.

Une ligne vide avant et après chaque ligne de séparation. Si --- est directement sous une ligne de texte, Markdown l'interprète comme une ligne de soulignement Setext H2 pour cette ligne, et non comme une ligne de séparation, ce qui décale tous les niveaux de titres suivants.

Écriture correcte : fin du paragraphe précédent → ligne vide → une ligne --- seule → ligne vide → titre suivant.

...fin de la section précédente...

---

1.2 Pourquoi en ai-je besoin ?
---

...contenu de cette section...

4-5 Autres règles strictes

La numérotation augmente d'un chiffre exactement à chaque niveau (1 → 1.1 → 1.1.1 → 1.1.1.1), sans sauter de niveau. Les numéros d'un même niveau doivent être consécutifs (2.1 puis 2.2, pas 2.4).
Les niveaux 1 et 2 utilisent les soulignements Setext (=== / ---), pas # / ## ; les niveaux 3 et 4 utilisent ### / ####. Ne pas les mélanger, # 1\. Introduction est incorrect.
Ne pas dépasser le niveau 4. Si une granularité plus fine est nécessaire, cela signifie que la section doit être divisée ou réorganisée.
Tous les titres commençant par # doivent avoir un numéro. Seule exception : l'étiquette de description du bloc de code dans le conteneur :::success (voir 5-1), qui utilise #### `Exemple de code : brève description`. En dehors de cela, aucun titre non numéroté n'est autorisé.
Le texte des titres est toujours en chinois traditionnel, quelle que soit la langue utilisée par l'utilisateur pour donner ses instructions.

4-6 Exemple de structure complète

---
title: Tutoriel d'introduction à Vite
tags: Vite, Frontend, Tutoriel
---

1\. Introduction
===

1.1 Qu'est-ce que c'est ?
---

Contenu explicatif...

---

1.2 Pourquoi en ai-je besoin ?
---

Contenu explicatif...

---

2\. Méthode d'installation
===

Avant de commencer l'installation, veuillez vérifier les points suivants :

---

2.1 Configuration système requise
---

### 2.1.1 Systèmes d'exploitation supportés

Contenu explicatif...

### 2.1.2 Paquets dépendants

Contenu explicatif...

---

2.2 Étapes d'installation
---

### 2.2.1 Installation avec un gestionnaire de paquets

#### 2.2.1.1 Environnement Windows

Contenu explicatif...

#### 2.2.1.2 Environnement macOS

Contenu explicatif...

Cet exemple illustre également :

1.1 est directement sous le === de 1\. Introduction, donc pas de ligne de séparation.
2.1 a du texte au-dessus, donc une ligne de séparation est ajoutée.
2\. Méthode d'installation n'est pas le premier titre, donc une ligne de séparation est ajoutée au-dessus.

Étape 5 : Styles de blocs HackMD

5-1 Blocs de code

Chaque bloc de code de l'article doit être enveloppé dans un conteneur :::success de HackMD, et respecter les règles suivantes :

La première ligne du conteneur contient une étiquette de description, au format fixe #### `Exemple de code : brève description` : utiliser un titre ####, le texte de l'étiquette entre une paire d'accents graves, sans emoji, ni numéro. C'est la seule exception à la règle 4-5 « Les titres doivent avoir un numéro ».
Une ligne vide entre l'étiquette de description et le bloc de code.
Le bloc de code doit toujours indiquer le langage (bash, html, csharp, json, etc.).
Pour un bloc de code de 3 lignes ou plus, ajouter un = après le nom du langage pour afficher les numéros de ligne (ex : ```html=) ; pour les courtes commandes d'1 à 2 lignes, ne pas ajouter =, pour éviter un affichage encombré.
Les exemples doivent pouvoir être copiés et exécutés directement ; après le bloc de code (à l'extérieur du conteneur), expliquer en une ou deux phrases ce que l'on verra après l'exécution.

Exemple de bloc de code multiligne :

:::success
#### `Exemple de code : Création d'un premier projet Vite`

```bash=
npm create vite@latest my-app
cd my-app
npm install
npm run dev
```
:::

Après exécution, le terminal affiche une URL locale (par exemple `http://localhost:5173`) ; ouvrez-la dans un navigateur pour voir la page d'exemple.

Exemple de commande courte :

:::success
#### `Exemple de code : Vérification de la version de Node.js`

```bash
node -v
```
:::

5-2 Encadrés d'alerte

Pour les contenus qui nécessitent une attention particulière du lecteur (erreurs fréquentes chez les débutants, concepts à retenir absolument), utiliser le format d'encadré suivant, avec une ligne de séparation --- avant et après l'encadré. Les lignes de séparation respectent la règle « ligne vide avant et après » :

...contenu précédent...

---

>[!Warning] 💡 **Astuce importante**
>
>---
> Si vous ne comprenez rien, **souvenez-vous juste de cette seule commande**.
> Après chaque étape, l'outil vous dira quoi taper ensuite.

---

...contenu suivant...

Les encadrés ne sont utilisés que pour les points vraiment importants, un ou deux maximum par section ; en utiliser trop réduit leur efficacité.
Si un encadré est immédiatement suivi d'un titre de niveau 1 ou 2 qui nécessite une ligne de séparation, le --- de fin de l'encadré sert également de ligne de séparation pour ce titre. Ne mettre qu'une seule ligne de séparation, pas deux --- consécutifs.

Étape 6 : Auto-vérification avant la sortie

Avant de livrer, vérifier chaque point de la liste sur l'ensemble de l'article ; corriger tout problème trouvé avant de le produire :

Étape 7 : Produire le résultat final

Par défaut, le fichier est livré sous forme de fichier .md, dont le nom utilise le nom du sujet, par exemple Vite-Introduction-Tutoriel.md. Les articles de tutoriel sont souvent longs ; les enregistrer sous forme de fichier permet à l'utilisateur de les copier intégralement dans HackMD, et évite les problèmes de troncature des blocs de code dans le dialogue. Dans la conversation, se contenter d'expliquer brièvement le contenu de l'article.
Si l'utilisateur demande que le contenu soit affiché directement dans le dialogue, ou si l'environnement actuel ne dispose pas d'outil pour créer un fichier, afficher le texte intégral dans le dialogue. Comme l'article contient des blocs de code avec ```, il faut envelopper l'ensemble de l'article avec quatre accents graves ou ~~~ pour éviter que les blocs de code internes ne ferment prématurément le bloc externe, ce qui provoquerait une rupture du contenu.
Après la livraison, lister brièvement les principales sources de référence utilisées (liens vers la documentation officielle, articles de référence importants), pour permettre à l'utilisateur de vérifier par lui-même ou d'approfondir ses connaissances.

johnsonshsu/claudecodedemo

Qu'est-ce que claudecodedemo ?

Demander à votre IA préférée

Documentation