Guide Markdown et documentation

Utiliser de l’ASCII dans un README GitHub

Dans un README GitHub, placez l’art ASCII dans un bloc de code délimité pour conserver ses lignes et ses espaces. Si le dessin contient déjà des accents graves consécutifs, choisissez une clôture plus longue. Ajoutez toujours un titre ou une description lisible en texte ordinaire.

Intégrer un dessin dans un README

Rédigez le nom du projet et sa description en texte ordinaire.
Ajoutez une ligne vide, puis une ligne de trois accents graves ```.
Collez le dessin sans retirer ses espaces ; fermez le bloc avec trois accents graves sur une ligne séparée.
Prévisualisez le README avant de l’enregistrer et vérifiez-le dans une fenêtre étroite.

La documentation GitHub sur les blocs de code décrit les blocs délimités et leur coloration facultative. Pour de l’art ASCII, un bloc sans étiquette de langage évite une coloration inutile. N’entourez pas chaque ligne de balises HTML : le bloc suffit.

Le dessin doit accompagner une information utile. Conservez le nom, le rôle du projet et les instructions d’installation sous une forme lisible sans décoder une bannière.

Cas 1 — Un README avec un chat de 7 colonnes

Voici un exemple complet à placer dans un fichier README.md. Le dessin contient 3 lignes et mesure au maximum 7 colonnes ; le titre et la phrase descriptive restent en dehors du bloc.

# Atelier

Petit chat de bienvenue.

```
 /\_/\
( o.o )
 > ^ <
```

Exemple autonome de README : titre, description, puis dessin dans un bloc délimité.

Résultat attendu : un titre « Atelier », une phrase descriptive et un bloc avec les trois lignes du chat. Les deux lignes de trois accents graves ne sont pas affichées comme du contenu. Les caractères _ et > du dessin ne servent pas à mettre le texte en forme.

Le diagnostic du dessin seul indique 21 points de code avec les deux sauts de ligne, sans saut final. Pour contrôler un encadrement plus régulier, utilisez également le cadre de 8 colonnes du guide principal.

Cas 2 — Le contenu contient déjà trois accents graves

Une clôture trop courte peut terminer le bloc au mauvais endroit. Dans cet exemple, le contenu doit conserver deux lignes de trois accents graves : les délimiteurs extérieurs en comportent donc quatre.

````
Example with an internal fence:
```
OK
```
````

Les lignes extérieures utilisent quatre accents graves. Les deux lignes de trois accents graves appartiennent au contenu affiché.

Résultat attendu : un seul bloc présentant les quatre lignes intérieures, avec les deux lignes ``` visibles. Le bloc ne s’interrompt pas après la phrase d’introduction. Ce mécanisme est décrit dans la spécification GitHub Flavored Markdown.

La règle pour une copie automatique fiable

Comptez la plus longue suite d’accents graves consécutifs dans le contenu. Choisissez une clôture d’au moins trois caractères et strictement plus longue que cette suite. Ainsi : aucune suite interne donne trois ; trois internes donnent quatre ; quatre internes donnent cinq.

max_run = longest_consecutive_backtick_run(drawing)
fence = "`" * max(3, max_run + 1)
markdown = fence + "\n" + drawing + "\n" + fence

Pseudocode : la clôture dépend du contenu. Le diagnostic d’ArtASCII utilise cette logique pour la copie destinée à GitHub.

Les deux clôtures doivent commencer sur leur propre ligne. Ne confondez pas un délimiteur extérieur nécessaire au Markdown avec les caractères que vous voulez réellement montrer.

Bannière FIGlet, dessin texte ou image : que choisir ?

Besoin	Choix proposé	Point de vigilance
Nom décoratif d’un outil en ligne de commande	Bannière créée avec le générateur texte.	Conserver un titre textuel accessible à côté ; éviter une bannière trop large.
Petit animal ou marque d’accueil	Chat ASCII court dans un bloc.	Éviter qu’un élément décoratif repousse les instructions importantes.
Schéma ou architecture utile à comprendre	Description structurée et représentation adaptée au sujet.	Un dessin décoratif ne remplace pas une explication des relations.
Photo convertie ou composition très large	Image PNG accompagnée d’un texte alternatif.	L’image fige la disposition, mais ses caractères ne sont plus copiables.
Exemple destiné à être modifié	Bloc de code et, si nécessaire, fichier TXT associé.	Conserver l’encodage et les espaces lors des modifications.

Une bannière FIGlet utilise une police dont les grandes lettres sont elles-mêmes composées de caractères ; voir le manuel officiel FIGlet. Vérifiez les crédits et les conditions de la police lorsque vous redistribuez ses fichiers.

Diagnostiquer un dessin décalé

Collez le texte à vérifier (100 000 caractères maximum)

Analyse locale : le texte reste dans votre navigateur. La mesure Unicode compte les points de code, pas les colonnes réellement affichées.

Contrôles avant publication

Espaces et tabulations

Gardez les espaces en début de ligne. Un outil qui nettoie automatiquement les lignes peut supprimer des espaces significatives. Préférez des espaces ordinaires à des tabulations et contrôlez la différence dans le fichier source.

Caractères invisibles et largeur

Un collage peut apporter une espace insécable ou un caractère invisible. Le diagnostic indique leur présence sans prédire leur effet dans chaque moteur de rendu. Pour de l’ASCII strict, la largeur en caractères est un repère simple ; pour Unicode, les emoji et les accents combinés demandent une vérification visuelle.

HTML et caractères spéciaux

Dans un bloc Markdown, conservez les caractères du dessin, y compris < et &. Si vous les écrivez comme texte dans votre propre HTML, utilisez un élément <pre> et échappez correctement le contenu. Copier du code HTML d’affichage à la place du dessin produirait une autre entrée.

README GitHub et site GitHub Pages

Un README rendu sur GitHub et une page générée par votre thème ne sont pas le même contexte. Pour GitHub Pages, vérifiez aussi les styles du site : police, traitement des espaces et débordement. La spécification CSS Text du W3C explique le rôle des espaces préservés et des retours de ligne.

Accessibilité, limites et réutilisation

Décrivez le dessin en une phrase s’il apporte une information. Si vous choisissez un PNG, écrivez un texte alternatif qui explique son rôle ; évitez un long inventaire de caractères. Une grande bannière ne doit pas être l’unique manière de lire le nom du projet.

Les exemples de cette page sont des chaînes de contrôle complètes. La syntaxe suit la documentation GitHub et sa spécification Markdown ; le rendu de chaque thème, extension, terminal ou application n’est pas certifié. Le diagnostic n’est pas un audit d’accessibilité et ne mesure pas la largeur en pixels.

Pour prolonger le travail, comparez les modèles, vérifiez les différences entre ASCII et Unicode ou consultez la procédure spécifique à Discord. La syntaxe d’une destination ne doit pas être supposée identique partout.