Développer avec l'IA : quand préférer HTML à Markdown ?

Quand on développe avec une IA, on accumule vite des fichiers Markdown : plans, notes d’architecture, comptes rendus de tests. Le format est commode. Mais au moment de valider un parcours ou de comparer deux propositions, demander une page HTML peut rendre la relecture beaucoup plus concrète.

Une liste peut décrire les étapes d’un formulaire sans montrer qu’un écran contient trop de champs. Un paragraphe peut annoncer « un message d’erreur clair » sans permettre de juger sa place ou son texte. Le HTML donne quelque chose à ouvrir et à examiner. L’intérêt se situe dans ce retour humain, sans présumer que des balises amélioreraient à elles seules les capacités du modèle.

Ce que le format change pour la personne qui relit

Prenons un projet fictif de suivi des demandes clients. L’IA propose une liste des fonctionnalités : déposer une demande, joindre une pièce, consulter son avancement. C’est une base de discussion, mais chacun peut imaginer une interface différente derrière ces quelques lignes.

Demandez une maquette HTML avec des données fictives. Vous pouvez alors voir si l’état « en attente d’un document » ressort suffisamment, si le bouton pour joindre une pièce se trouve au bon endroit, ou si le parcours reste compréhensible sur un petit écran.

Le retour devient précis : « afficher la pièce manquante près du statut » ou « conserver le texte saisi après cette erreur ». L’IA dispose d’une correction délimitée à appliquer. Le client peut aussi participer sans devoir lire le code.

Pour un rapport technique, la même logique consiste à placer les options côte à côte et à rendre les hypothèses visibles. La présentation doit faciliter une décision. Si elle ajoute seulement des couleurs à un texte déjà clair, le détour apporte peu.

Markdown sait déjà produire des pages web

Markdown est pensé pour écrire du texte lisible et le convertir en HTML. Sa documentation d’origine prévoit aussi l’insertion de HTML lorsque sa syntaxe ne couvre pas le besoin. Un fichier Markdown peut donc tout à fait être à l’origine d’une page soignée.

Avec un fichier HTML autonome, vous choisissez la mise en page et les interactions utiles à la relecture. La personne qui l’ouvre n’a pas besoin du même éditeur que vous. Si votre documentation possède déjà un bon rendu avec des composants adaptés, il peut suffire de l’utiliser.

Quel format demander à l’IA ?

Nous choisirions le format à partir de la personne qui doit utiliser le résultat et de la décision qu’elle doit prendre.

Les consignes de l’agent doivent rester dans les fichiers qu’il sait charger. Renommer un fichier de règles en .html ne suffit pas à le rendre utilisable. De même, pour du texte long destiné surtout à être corrigé ligne par ligne, Markdown évite d’ajouter du balisage autour de chaque paragraphe.

Un exemple HTML à ouvrir dans le navigateur

Ce petit document sépare un scénario de recette de la décision qui reste à prendre. Enregistrez-le sous recette.html, puis ouvrez-le dans un navigateur. Il contient son CSS et fonctionne sans dépendance ni JavaScript.

<!doctype html>
<html lang="fr">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Recette du dépôt de documents</title>
    <style>
      * { box-sizing: border-box; }
      body {
        max-width: 48rem;
        margin: auto;
        padding: 2rem 1rem;
        font: 1rem/1.6 system-ui, sans-serif;
        color: #182235;
        background: #fafbfe;
      }
      h1 { line-height: 1.2; }
      section, details {
        margin-block: 1.5rem;
        padding: 1.25rem;
        border: 1px solid #a9b8d0;
        border-radius: .5rem;
      }
      summary { cursor: pointer; font-weight: 700; }
      summary:focus-visible { outline: 3px solid #2459ad; }
      .decision { border-left: 4px solid #2459ad; }
    </style>
  </head>
  <body>
    <main>
      <h1>Déposer un document</h1>
      <p>Exemple fictif. Statut : scénario à tester.</p>
      <section aria-labelledby="scenario">
        <h2 id="scenario">Si le fichier dépasse la taille autorisée</h2>
        <p>Le formulaire explique le refus et conserve les autres champs.</p>
        <p>Vérification prévue : essayer au clavier et sur mobile.</p>
      </section>
      <aside class="decision" aria-label="Décision en attente">
        <p><strong>À confirmer :</strong> quelle taille maximale accepter ?</p>
      </aside>
      <details>
        <summary>Consulter le critère d'acceptation</summary>
        <p>Après le refus, l'utilisateur peut choisir un autre fichier
          sans recommencer sa demande.</p>
      </details>
    </main>
  </body>
</html>

Le bloc dépliable repose sur les éléments natifs details et summary, décrits par MDN. Le navigateur gère l’ouverture, y compris au clavier. Le texte « scénario à tester » reste visible : la présentation n’attribue pas au test un résultat qui n’a pas été obtenu.

Pour une maquette interactive plus complète, le JavaScript peut devenir nécessaire. Demandez-le pour un comportement précis, par exemple simuler le refus d’un fichier. Inutile d’installer un framework juste pour afficher quelques décisions.

Un prompt pour obtenir un document utile

Indiquez à l’IA qui lira le document et ce que cette personne doit vérifier. Une demande limitée à l’apparence peut produire une page agréable qui laisse les questions difficiles dans les paragraphes du bas.

Prépare un rapport de revue en un seul fichier HTML autonome, avec son CSS intégré. Il sera lu par le responsable du projet. Utilise uniquement les faits présents dans les notes jointes. Distingue les observations, les hypothèses et les décisions à prendre. Place la synthèse en tête, puis un tableau comparatif si les options s’y prêtent. Utilise des détails dépliables pour les explications secondaires. Garde les points bloquants visibles. Prévois une lecture sur mobile et au clavier, sans dépendance externe. Signale les informations manquantes au lieu de les compléter.

Après la génération, ouvrez réellement le fichier. Si votre agent dispose d’un outil de navigateur, vous pouvez lui demander d’examiner le rendu ou une capture et de corriger un débordement. Un agent qui lit uniquement le code n’a pas automatiquement accès à son apparence à l’écran.

Garder les décisions faciles à retrouver

Le principal piège arrive après la première validation : le plan Markdown dit une chose et le rapport HTML en dit une autre. Pour l’éviter, choisissez où vivent les décisions. Le HTML peut servir à la revue, puis les décisions retenues rejoignent la documentation du dépôt. Autre possibilité : générer la présentation à partir d’une source commune.

Demandez aussi des modifications ciblées. Si seule la règle sur les pièces jointes change, il n’est pas nécessaire de réécrire tout le rapport. Un HTML correctement indenté reste un fichier texte que Git peut suivre ; une page minifiée ou remplie de styles répétés rend la comparaison moins agréable.

Enfin, conservez une copie du fichier autonome lorsque vous voulez figer une revue. Pour un document destiné à l’impression, il faudra travailler la pagination : notre guide sur la génération de PDF détaille cette étape.

Sur votre prochain projet avec l’IA, essayez ce format sur un seul livrable difficile à relire. Un plan de migration ou un parcours de formulaire suffit. Regardez si les personnes concernées repèrent mieux les questions ouvertes et formulent des corrections plus précises. C’est à cet usage que le HTML peut justifier le travail supplémentaire de présentation.