Le Markdown est le format dans lequel j'écris presque tout - READMEs, documentation du plugin, notes de version, descriptions des demandes d'extraction, le journal des modifications pour WP Adminify, la moitié de mes notes internes. Il s'écarte de chaque construction sauf une. Au moment où une table est impliquée, j'arrête d'écrire et commence à compter les caractères du tuyau, et le flux est parti. Ajoutez une colonne à une table à cinq lignes et vous modifiez six lignes à la main, plus la ligne du délimiteur, et vous ne saurez pas si vous avez bien compris jusqu'à ce que la page se rende.
tl;dr : le Générateur de tables de démar vous donne une grille de type feuille de calcul, génère un Markdown Saveur GitHub valide au fur et à mesure que vous tapez, et importe CSV, pâte de feuille de calcul ou une table Markdown existante afin que vous puissiez la restructurer Définir l'alignement par colonne en un clic, et exporter Markdown, HTML ou CSV. Tout s'exécute dans votre navigateur.
L'outil existe parce que la syntaxe de table est la seule partie de Markdown où le format source combat activement l'édition Ce guide couvre le fonctionnement des tables GFM, les règles qui décident si le vôtre rend, les pièges qui s'échappent qui brisent les lignes et comment utiliser le générateur pour les tables de workflows proviennent généralement - une feuille de calcul, un résultat de requête ou un tableau que quelqu'un a déjà écrit.
Qu'est-ce qu'une table Markdown ?
Une table de Markdown est composée de trois ingrédients empilés dans un ordre fixe : une ligne d'en-tête, une ligne de délimitation et zéro ou plusieurs lignes de corps. Les tables ne font pas du tout partie du Markdown principal - elles sont une extension définie par le Spécification de Markdown aromatisée GitHub[traduction], c'est pourquoi une table peut s'afficher sur GitHub et sortir comme des tuyaux littéraux ailleurs Les cellules sont séparées par des caractères de tuyau, et chaque rangée occupe exactement une ligne.
| Tool | Category | Offline |
| --- | --- | --- |
| JSON Formatter | Coding | Yes |
| YAML to JSON | Data | Yes |
La ligne délimiteur est la partie qui en fait un tableau plutôt qu'un paragraphe contenant des tuyaux Elle doit être la deuxième ligne, elle doit être constituée de tirets avec des deux-points optionnels, et elle doit avoir le même nombre de cellules que l'en-tête Obtenez n'importe lequel de ces faux et le moteur de rendu traite le bloc entier comme du texte ordinaire - c'est pourquoi " ; ma table rend comme du texte brut" ; est presque toujours un problème de ligne délimiteur.
Les tableaux ne font pas partie de la spécification CommonMark originale Ils sont arrivés en tant qu'extension GitHub Flavored Markdown et ont ensuite été adoptés presque partout : GitHub, GitLab, Bitbucket, Obsidian, Notion, Docusaurus, MkDocs, VitePress, Hugo, Jekyll, Discord et la plupart des générateurs de sites statiques. " ; Almost" ; est le mot opérationnel Un moteur de rendu CommonMark minimal sans extension affichera votre table sous forme de tuyaux littéraux, et le correctif consiste à émettre du HTML à la place - ce que le générateur peut faire en un clic sur les onglets de sortie.
Pourquoi la syntaxe est plus difficile à maintenir qu'elle n'en a l'air
Lire un tableau de Markdown est facile Le maintien d'un est l'endroit où le coût se cache, et il vient de quatre endroits.
La structure vit dans la ponctuation. Il n'y a pas de limite de cellule, sauf un caractère qui apparaît également dans les expressions régulières, les commandes shell et les types d'union TypeScript. Chacun de ceux à l'intérieur d'une cellule doit être échappé ou la ligne gagne silencieusement une colonne.
L'alignement est codé dans le placement des deux-points. Un deux-points à gauche signifie aligné à gauche, un deux-points des deux côtés signifie centré, un deux-points à droite signifie aligné à droite Il n'y a pas de mot-clé pour s'en souvenir, et la différence entre ---: et :--- est-ce qu'un personnage d'affilée, personne ne lit attentivement.
L'édition est multiligne. Ajouter une colonne signifie toucher chaque ligne plus le délimiteur Réordonnancer les lignes signifie couper et coller sans retour visuel Supprimer une colonne est une recherche du nième tuyau sur chaque ligne.
L'alignement de la source est manuel. Les colonnes rembourrées ne sont pas obligatoires - les moteurs de rendu ignorent les espaces supplémentaires - mais les tables non rembourrées sont misérables à lire dans une comparaison, donc les gens les rembourrent à la main, puis les recadrent à chaque fois qu'un contenu de cellule et n°39 ; augmente.
Un éditeur de grille supprime les quatre Vous modifiez des cellules ; la syntaxe est générée C'est toute la prémisse de l'outil.
Comment utiliser le générateur de table de Markdown
Étape 1 : Obtenez vos données dans la grille
Trois itinéraires vers l'intérieur, selon l'endroit où vivent déjà les données.
Tapez-le. La grille s'ouvre avec un échantillon rempli Écrasez les cellules, ou appuyez sur Effacer pour un trois-par-trois vide et recommencez.
Coller à partir d'une feuille de calcul. Ouvrez le panneau Importer et collez une plage copiée depuis Excel, Google Sheets, Numbers ou LibreOffice. Les feuilles de calcul placent du texte séparé par onglets dans le presse-papiers, et l'importateur le détecte automatiquement - pas besoin de lui indiquer quel délimiteur vous utilisez.
Coller CSV ou une table existante. Le même panneau accepte les tables CSV, semicolon-séparé (la valeur par défaut dans de nombreux lieux européens), pipe-delimited text, et Markdown Si le texte ressemble à une table Markdown - une ligne d'en-tête suivie d'une ligne délimiteur - il est analysé comme un, y compris ses alignements de colonnes, afin que vous puissiez charger une table à partir d'un README, le restructurer, et le coller en arrière.
L'importation CSV suit les règles de la RFC 4180 plutôt que de se diviser naïvement sur les virgules Un champ cité peut contenir des virgules, des sauts de ligne et des guillemets doublés qui représentent un caractère de guillemet littéral Cela compte plus que ce qu'il semble : toute exportation contenant une adresse, une description ou un prix dans un lieu qui utilise des virgules brisera une division naïve, et vous ne le remarquerez pas tant qu'une colonne n'est pas courte d'une cellule Si votre CSV est suffisamment grand pour que vous souhaitiez l'inspecter avant d'importer, le Visionneuse CSV l'ouvre d'abord dans une grille triable.
Étape 2 : Façonnez la table
Les commandes autour de la grille couvrent les opérations douloureuses en Markdown brut :
- Rangée et Colonne ajouter à la fin de la grille.
- Les flèches à côté de chaque ligne le déplacent vers le haut ou vers le bas - utile pour classer une table de comparaison selon ce que vous décidez le plus important.
- Le bouton moins d'une ligne ou d'un en-tête de colonne le supprime, sur chaque ligne à la fois.
- Transposer échange des lignes et des colonnes Les données collées à partir d'un rapport sont fréquemment orientées dans le mauvais sens pour un document, et la transposition est d'un clic au lieu d'un retape complet.
Étape 3 : Définissez l'alignement par colonne
Chaque en-tête de colonne porte trois boutons d'alignement : gauche, centre, droite Cliquez-en un pour l'appliquer, cliquez-le à nouveau pour revenir au moteur de rendu' ; s par défaut Le générateur écrit les deux-points correspondants dans la ligne du délimiteur.
L'alignement vaut la peine d'être utilisé délibérément Les colonnes numériques - prix, comptes, pourcentages, durées - lisent beaucoup mieux alignées à droite, car les chiffres s'alignent par valeur de lieu Les valeurs d'état courtes semblent bien centrées Le texte appartient à gauche Ce n'est pas de la décoration ; une colonne de nombres alignée à droite est véritablement plus rapide à rechercher la plus grande valeur.
Étape 4 : Choisissez le format de sortie et copiez
Trois onglets de sortie :
Marquage produit GFM. Le Colonnes rembourrées toggle contrôle si les cellules sont remplies d'espaces afin que la source brute s'aligne dans un éditeur monospace. Le remplissage ne change rien à la façon dont le tableau se rend - il s'adresse uniquement à celui qui lit le fichier dans une différence. Tuyaux extérieurs contrôle le tuyau avant et arrière sur chaque rangée ; les deux styles sont valides et le style de tuyau avant est de loin la convention la plus courante.
HTML produit un <table> avec <thead> et <tbody> et en ligne text-align styles correspondant aux alignements de vos colonnes Utilisez-le pour les moteurs de rendu qui manquent de support de table, pour les modèles de messagerie ou lorsque vous en avez besoin colspan et des cellules multilignes que Markdown ne peut pas exprimer Si vous voulez aller dans l'autre sens et soulever une table hors d'une page web, HTML à Markdown le gère.
CSV vous donne la grille sous forme de données, correctement citées, pour coller dans une feuille de calcul ou alimenter un script.
Copiez dans le presse-papiers ou téléchargez-le sous forme de .md, .html, ou .csv fichier.
Les règles d'échappement qui brisent réellement les tables
Deux caractères provoquent presque toutes les tables de démarque cassées, et les deux sont gérés automatiquement par le générateur - mais vous devez connaître les règles des tables que vous modifiez à la main.
Le tuyau. Un tuyau littéral à l’intérieur d’une cellule doit s’écrire ainsi \|. Sans le jeu de barres arrière, le moteur de rendu voit un séparateur de colonnes et votre ligne gagne une cellule, jetant chaque colonne après. Cela mord le plus fort dans la documentation technique, où les cellules contiennent légitimement des choses comme string | null, grep foo | wc -l(en), ou une alternance regex. L'échappement fonctionne même à l'intérieur de backtick code spans - un cas rare où Markdown' ; s usual " ; code spans sont littéral" ; règle ne s'applique pas.
La nouvelle ligne. Les tables GFM sont strictement une ligne par ligne, donc une cellule ne peut pas contenir de véritable coupure de ligne La solution de contournement universelle est un HTML <br> balise. Lorsque vous collez du contenu multiligne dans la grille, le générateur insère la balise pour vous ; lorsque vous importez une table contenant <br>(,) il se reconvertit en une véritable coupure de ligne dans l'éditeur afin que la cellule soit confortable à éditer.
Deux autres règles valent la peine d'être mises en mémoire car elles provoquent " ; ma table ne rend pas " ; des rapports qui n'ont rien à voir avec la table elle-même Tout d'abord, une table a besoin d'une ligne vierge avant elle lorsqu'elle suit un paragraphe Deuxièmement, à l'intérieur d'un élément de liste, la table entière doit être en retrait de la colonne de contenu list item' ; s - sinon la liste avale la première ligne et la ligne de délimitation atterrit au mauvais endroit.
D'où viennent les tableaux et comment chaque cas circule
Une feuille de calcul qu'on vous a envoyée
Copiez la plage, collez dans le panneau Importer, chargez-la dans la grille, supprimez les colonnes dont personne n'a besoin, alignez à droite celle numérique, copiez le Markdown. Moins d'une minute pour un tableau qui prendrait dix au format manuel.
Un résultat de requête ou une réponse API
Données qui commencent comme JSON a généralement besoin d'un saut Convertir avec JSON vers CSV« , puis collez le CSV dans l'importateur. » En allant dans l'autre sens - une table de Markdown dont vous avez besoin comme données - exportez le CSV des onglets de sortie et exécutez-le CSV à JSON.
Une table qui existe déjà dans un README
Collez-le dans le panneau Importer Il revient dans la grille avec ses alignements intacts, donc ajouter une colonne ou réorganiser des lignes est une modification normale plutôt qu'une réécriture C'est le flux de travail que j'utilise le plus : les tables de documentation grandissent d'une ligne à la fois pendant des mois, puis ont besoin d'être restructurées d'un seul coup.
Un tableau comparatif que vous écrivez à partir de zéro
Commencez par la grille, tapez comme vous le pensez et laissez le remplissage se régler. Écrire une comparaison dans une grille plutôt que dans la syntaxe du tuyau permet de déterminer si la comparaison est juste plutôt que si les colonnes s'alignent.
Documentation qui doit fonctionner dans plusieurs moteurs de rendu
Générez le Markdown pour les plates-formes qui prennent en charge les tables GFM, puis basculez l'onglet de sortie en HTML pour celle qui ne le fait pas. Même grille, deux exportations, aucun retapage Si votre pipeline convertit Markdown en HTML de toute façon, Markdown en HTML vous montre exactement ce que produit la conversion.
Tableaux de démarque par rapport aux tableaux HTML
| considération | Tableau de démarquage | Tableau HTML |
|---|---|---|
| Lisibilité de la source | Haut - scannable en texte brut | Les balises basses dominent le contenu |
| Cellules multilignes | Uniquement via <br> |
Natif, tout contenu de bloc |
| Cellules fusionnées | Non pris en charge | colspan et rowspan |
| Alignement par colonne | Oui, via des côlons délimiteurs | Oui, via CSS ou attributs |
| Contrôle de style | nul | CSS complet |
| Support des fournisseurs | Extension de la GFM, généralisée mais pas universelle | Universel partout où HTML est autorisé |
| Diffamabilité | Bien, une ligne par ligne | Pauvre, beaucoup de lignes par rangée |
La règle pratique : utilisez Markdown jusqu'à ce que vous ayez besoin d'une cellule fusionnée, d'un élément de bloc à l'intérieur d'une cellule ou d'un style spécifique. Ensuite, passez cette table au HTML et laissez le reste du document tranquille. La plupart des moteurs de rendu Markdown transmettent du HTML brut, donc mélanger les deux dans un seul fichier est normal.
Une note sur la vie privée
Les tables que les gens construisent sont souvent celles qu'ils préfèrent ne pas télécharger : prix non encore annoncés, effectifs, références internes, un client' ; les données collées à partir d'une feuille de calcul.
Le générateur est JavaScript côté client La grille, l'analyseur d'importation, et chaque exécution d'exportation dans la page, et rien de ce que vous collez ne quitte votre machine Chargez-le une fois et il continue de fonctionner hors ligne C'est le même principe derrière tout sur Toolz.dev, et le raisonnement vaut la peine d'être lu en entier dans le guide sur Confidentialité des données dans les outils en ligne. Si vous élaborez un ensemble plus large d'utilitaires basés sur un navigateur pour le travail quotidien, le Guide des outils de codage et le Boîte à outils pour les développeurs Web couvrez ce qui rapporte un signet.
Conseils pratiques
Gardez l'en-tête court. Avec le remplissage activé, la cellule la plus large d'une colonne définit la largeur de chaque ligne de la source. Un en-tête verbeux rend le fichier brut bruyant sans aucun avantage de rendu.
Ne craignez pas la sortie non ajoutée pour les fichiers générés. Si une table est écrite par un script et n'est jamais lue comme source, désactivez le remplissage et enregistrez les octets.
Trier avant de coller. Réordonner des lignes un clic-flèche à la fois est bien pour cinq lignes et fastidieux pour cinquante Trier dans la feuille de calcul d'abord, puis importer.
Surveillez la ligne d'en-tête vide. Avec " ; la première ligne est header" ; désactivé, le générateur émet un en-tête vide au-dessus de vos données, car GFM n'a aucun moyen d'exprimer une table sans en-tête Certains moteurs de rendu montrent que comme une fine ligne vierge Si cela vous dérange, exportez HTML à la place, qui n'a besoin d'aucun en-tête du tout.
Vérifiez le résultat rendu, pas la source. Une source rembourrée qui semble parfaite peut toujours donner tort si la ligne de délimitation comporte le mauvais nombre de cellules. Collez dans l'aperçu de la plate-forme sur laquelle vous publiez avant de l'appeler terminé.
FAQ
Comment créer une table dans Markdown ?
Une table de Markdown a besoin d'une ligne d'en-tête, d'une ligne de délimiteurs de tirets et d'une ligne par enregistrement, avec des cellules séparées par des caractères de tuyau Remplissez la grille dans le générateur et l'outil écrit cette syntaxe pour vous, y compris la ligne de délimiteurs et tous les deux points d'alignement.
Comment aligner les colonnes dans un tableau Markdown ?
L'alignement est défini avec des deux-points dans la ligne de délimitation : un deux-points à gauche s'aligne à gauche, des deux-points des deux côtés au centre et un deux-points à droite s'aligne à droite Choisissez un alignement dans un en-tête de colonne dans l'éditeur et le placement correct des deux-points est généré automatiquement.
Puis-je convertir une plage Excel ou Google Sheets en une table de démarque ?
Oui. Copiez les cellules de votre feuille de calcul et collez-les dans le panneau Importer. Les tableurs placent le texte séparé par onglets dans le presse-papiers, que l'importateur détecte automatiquement et charge dans la grille.
Comment mettre un caractère de tuyau dans une cellule de table ?
Un tuyau littéral doit être échappé avec une barre oblique inverse ou le moteur de rendu le lira comme un séparateur de colonnes Tapez le tuyau normalement dans l'éditeur et le générateur vous échappe dans la sortie pour vous.
Une cellule de tableau Markdown peut-elle contenir plusieurs lignes ?
Pas avec de vraies lignes nouvelles, car les tables GFM sont strictement une ligne par ligne La solution de contournement habituelle est une balise HTML de rupture de ligne à l'intérieur de la cellule, que cet outil insère automatiquement lorsqu'une cellule que vous collez contient un saut de ligne.
Pourquoi mon tableau est-il rendu en texte brut sur GitHub ?
La rangée délimiteur en est presque toujours la cause : elle doit être la deuxième ligne et elle doit avoir le même nombre de cellules que l'en-tête Une ligne vierge manquante avant que la table puisse également l'arrêter de rendre lorsque la table suit un paragraphe ou se trouve à l'intérieur d'une liste.
Dois-je remplir les colonnes de sorte que la source s'aligne ?
Les Renderers n° ignorent les espaces supplémentaires, donc une table non rembourrée s'affiche de la même manière. Un remplissage existe pour les humains lisant le fichier brut dans un éditeur ou un diff. Éteignez-le avec la bascule de sortie complétée si vous préférez une source compacte.
Les tableaux de démarque sont-ils pris en charge partout ?
Les tables sont une extension GitHub Flavored Markdown plutôt qu'une partie de la spécification CommonMark originale GitHub, GitLab, Obsidian, Notion, Docusaurus et la plupart des générateurs de sites statiques les prennent en charge, mais certains moteurs de rendu minimaux ne le font pas. Basculez la sortie en HTML si la vôtre en fait partie.
