Markdown è il formato in cui scrivo quasi tutto - README, documentazione dei plugin, note di rilascio, descrizioni delle richieste pull, il changelog per WP Adminify, metà delle mie note interne Si toglie di mezzo per ogni costrutto tranne uno Nel momento in cui è coinvolta una tabella, smetto di scrivere e inizio a contare i caratteri del pipe, e il flusso è andato Aggiungere una colonna a una tabella di cinque righe e stai modificando sei righe a mano, più la riga del delimitatore, e non saprai se hai capito bene fino al rendering della pagina.
tl; dr: la Generatore di tabelle di Markdown ti offre una griglia in stile foglio di calcolo, genera un Markdown a sapore GitHub valido durante la digitazione e importa CSV, pasta per fogli di calcolo o una tabella Markdown esistente in modo da poterla ristrutturare Imposta l'allineamento per colonna con un clic ed esporta Markdown, HTML o CSV. Tutto viene eseguito nel browser.
Lo strumento esiste perché la sintassi della tabella è l'unica parte di Markdown in cui il formato sorgente combatte attivamente l'editing Questa guida copre il funzionamento delle tabelle GFM, le regole che decidono se il tuo rende, le trappole di fuga che interrompono le righe e come utilizzare il generatore per i flussi di lavoro da cui provengono solitamente le tabelle: un foglio di calcolo, un risultato della query o una tabella che qualcuno ha già scritto.
Che cosa è un tavolo Markdown?
Una tabella Markdown è composta da tre ingredienti impilati in un ordine fisso: una riga di intestazione, una riga di delimitatore e zero o più righe di corpo Le tabelle non fanno affatto parte del Markdown principale: sono un'estensione definita dal Specifiche Markdown aromatizzate GitHub, motivo per cui una tabella può eseguire il rendering su GitHub ed uscire come pipe letterali altrove Le celle sono separate da caratteri pipe e ogni riga occupa esattamente una riga.
| Tool | Category | Offline |
| --- | --- | --- |
| JSON Formatter | Coding | Yes |
| YAML to JSON | Data | Yes |
La riga del delimitatore è la parte che la rende una tabella piuttosto che un paragrafo contenente pipe Deve essere la seconda riga, deve essere composta da trattini con due punti opzionali e deve avere lo stesso numero di celle dell'intestazione. Prendi qualcuno di questi errori e il renderer tratta l'intero blocco come testo ordinario - motivo per cui & quot; la mia tabella esegue il rendering come testo semplice" è quasi sempre un problema di riga del delimitatore.
Le tabelle non fanno parte della specifica CommonMark originale Sono arrivate come estensione di GitHub Flavored Markdown e sono state successivamente adottate un pò ovunque: GitHub, GitLab, Bitbucket, Obsidian, Notion, Docusaurus, MkDocs, VitePress, Hugo, Jekyll, Discord e la maggior parte dei generatori di siti statici. & quot; Almost" è la parola operativa Un renderer minimo CommonMark senza estensioni mostrerà la tua tabella come pipe letterali e la correzione consiste invece nell'emettere HTML - cosa che il generatore può fare con un clic sulle schede di output.
Perché la sintassi è più difficile da mantenere di quanto sembri
Leggere una tabella Markdown è facile Mantenerne una è dove si nasconde il costo, e viene da quattro posti.
Struttura vive nella punteggiatura. Non esiste un confine di cella tranne un carattere che appare anche nelle espressioni regolari, nei comandi della shell e nei tipi di unione TypeScript. Ognuno di quelli all'interno di una cella deve essere sfuggito o la riga ottiene silenziosamente una colonna.
L'allineamento è codificato nel posizionamento del colon. Un colon a sinistra significa allineato a sinistra, un colon su entrambi i lati significa centrato, un colon a destra significa allineato a destra Non esiste una parola chiave con cui ricordarlo e la differenza tra ---: e :--- c'è un personaggio di fila che nessuno legge da vicino.
L'editing è multi-linea. Aggiungere una colonna significa toccare ogni riga più il delimitatore Riordinare righe significa tagliare e incollare senza feedback visivo Cancellare una colonna è una ricerca dell'ennesima pipa su ogni riga.
L'allineamento della sorgente è manuale. Le colonne imbottite non sono necessarie - i renderer ignorano gli spazi extra - ma le tabelle non imbottite sono miserabili da leggere in un diff, quindi le persone le imbottiscono a mano e poi le ri-imbottiscono ogni volta che un contenuto di cell's cresce.
Un editor di griglia rimuove tutti e quattro Si modificano le celle; viene generata la sintassi Questa è l'intera premessa dello strumento.
Come utilizzare il generatore di tabelle Markdown
Passaggio 1: inserisci i tuoi dati nella griglia
Tre percorsi, a seconda di dove già vivono i dati.
Digitalo. La griglia si apre con un campione riempito Sovrascrivi le celle, oppure premi Cancella per un tre per tre vuoto e ricomincia da capo.
Incolla da un foglio di calcolo. Apri il pannello Importa e incolla un intervallo copiato da Excel, Fogli Google, Numeri o LibreOffice I fogli di calcolo inseriscono testo separato da schede negli appunti e l'importatore lo rileva automaticamente: non è necessario indicargli quale delimitatore stai utilizzando.
Incolla CSV o una tabella esistente. Lo stesso pannello accetta CSV, esportazioni separate da punto e virgola (il valore predefinito in molte località europee), testo delimitato da pipe e tabelle Markdown Se il testo sembra una tabella Markdown - una riga di intestazione seguita da una riga di delimitatore - viene analizzato come uno, inclusi gli allineamenti delle colonne, in modo da poter caricare una tabella da un README, ristrutturarla e incollarla indietro.
L'importazione CSV segue le regole RFC 4180 piuttosto che dividere sulle virgole ingenuamente Un campo quotato può contenere virgole, interruzioni di riga e virgolette raddoppiate che rappresentano un carattere di virgolette letterale Ciò conta più di quanto sembri: qualsiasi esportazione contenente un indirizzo, una descrizione o un prezzo in un locale che utilizza virgole interromperà una divisione ingenua e non te ne accorgerai finché una colonna non sarà corta di una cella Se il tuo CSV è abbastanza grande da volerlo ispezionare prima dell'importazione, il Visualizzatore CSV lo apre prima in una griglia ordinabile.
Passaggio 2: modella la tabella
I controlli attorno alla griglia coprono le operazioni che sono dolorose nel Markdown grezzo:
- Fila e Colonna aggiungi alla fine della griglia.
- Le frecce accanto a ciascuna riga la spostano verso l'alto o verso il basso, utile per ordinare una tabella comparativa in base a qualunque cosa tu abbia deciso che conta di più.
- Il pulsante meno sull'intestazione di una riga o di una colonna lo elimina, su ogni riga contemporaneamente.
- Trasporre scambia righe e colonne I dati incollati da un report sono spesso orientati nel modo sbagliato per un documento e la trasposizione è un clic anziché un retype completo.
Passo 3: Imposta l'allineamento per colonna
Ogni intestazione di colonna porta tre pulsanti di allineamento: sinistra, centro, destra Fare clic su uno per applicarlo, fare nuovamente clic su di esso per tornare al valore predefinito di renderer' Il generatore scrive i due punti corrispondenti nella riga di delimitazione.
L'allineamento vale la pena di essere utilizzato deliberatamente Colonne numeriche - prezzi, conteggi, percentuali, durate - leggere molto meglio allineato a destra, perché le cifre si allineano in base al valore del luogo I valori di stato brevi sembrano ordinati centrati Il testo appartiene a sinistra Questa non è decorazione; una colonna di numeri allineata a destra è veramente più veloce da scansionare per il valore più grande.
Passo 4: Scegliere il formato di output e copiare
Tre schede di output:
Contrassegno produce GFM. IL Colonne imbottite toggle controlla se le celle sono imbottite di spazi in modo che la sorgente grezza si allinei in un editor monospaziale Il riempimento non cambia nulla su come viene eseguita la tabella: è puramente per chi legge il file in un diff. Tubi esterni controlla il tubo principale e quello posteriore su ciascuna fila; entrambi gli stili sono validi e lo stile del tubo principale è di gran lunga la convenzione più comune.
HTML produce a <table> di <thead> e <tbody> e in linea text-align stili corrispondenti agli allineamenti delle colonne Utilizzalo per i renderer privi di supporto per le tabelle, per i modelli di posta elettronica o quando ne hai bisogno colspan e celle multi-linea che Markdown non può esprimere Se si desidera andare nella direzione opposta e sollevare una tabella da una pagina web, HTML a Markdown lo gestisce.
CSV ti restituisce la griglia come dati, opportunamente citati, da incollare in un foglio di calcolo o da inserire in uno script.
Copia negli appunti o scarica come a .md, .html, o .csv file.
Le regole di fuga che effettivamente rompono i tavoli
Due caratteri causano quasi ogni tabella di Markdown suddivisa ed entrambi vengono gestiti automaticamente dal generatore, ma dovresti conoscere le regole per le tabelle che modifichi manualmente.
Il tubo. Una pipa letterale all'interno di una cella deve essere scritta come \|. Senza la barra rovesciata, il renderer vede un separatore di colonne e la tua riga guadagna una cella, buttando via ogni colonna dopo di essa Questo morde più forte nella documentazione tecnica, dove le celle contengono legittimamente cose come string | null, grep foo | wc -l, o un'alternanza regex L'escape funziona anche all'interno di codicing backtick - un raro caso in cui Markdown's usuale & quot; le campate di codic sono letteral" regola non si applica.
La newline. Le tabelle GFM sono rigorosamente una riga per riga, quindi una cella non può contenere una vera interruzione di riga La soluzione alternativa universale è un HTML <br> tag. Quando incolli contenuti multi-linea nella griglia, il generatore inserisce il tag per te; quando importi una tabella contenente <br>, si converte nuovamente in una vera interruzione di riga nell'editor in modo che la cella sia comoda da modificare.
Vale la pena impegnare altre due regole nella memoria perché causano & quot; la mia tabella non rende& quot; rapporti che non hanno nulla a che fare con la tabella stessa Innanzitutto, una tabella ha bisogno di una riga vuota prima di essa quando segue un paragrafo In secondo luogo, all'interno di un elemento di elenco, l'intera tabella deve essere rientrata nella colonna del contenuto dell'elemento di elenco's - altrimenti l'elenco ingoia la prima riga e la riga del delimitatore finisce nel posto sbagliato.
Da dove provengono le tabelle e come scorre ogni caso
Un foglio di calcolo che ti è stato inviato
Copia l'intervallo, incolla nel pannello Importa, caricalo nella griglia, elimina le colonne di cui nessuno ha bisogno, allinea a destra quella numerica, copia il Markdown. Meno di un minuto per una tabella che richiederebbe dieci per essere modellata manualmente.
Un risultato di una query o una risposta API
Dati che iniziano come JSON di solito ha bisogno di un salto Convertilo con JSON a CSV, quindi incollare il CSV nell'importatore Andando dall'altra parte - una tabella Markdown che avete bisogno come dati - esportare CSV dalle schede di output ed eseguirlo attraverso CSV a JSON.
Una tabella che esiste già in un README
Incollalo nel pannello Importa. ritorna nella griglia con i suoi allineamenti intatti, quindi aggiungere una colonna o riordinare le righe è una modifica normale piuttosto che una riscrittura Questo è il flusso di lavoro che uso di più: le tabelle di documentazione crescono di una riga alla volta per mesi, quindi necessitano di ristrutturazione tutte in una volta.
Una tabella di confronto che stai scrivendo da zero
Inizia con la griglia, digita come pensi e lascia che il riempimento si sistemi Scrivendo un confronto in una griglia invece che nella sintassi della pipe, mantieni la tua attenzione sul fatto che il confronto sia corretto piuttosto che sul fatto che le colonne si allineino.
Documentazione che deve funzionare in diversi renderer
Genera il Markdown per le piattaforme che supportano le tabelle GFM, quindi passa la scheda di output all'HTML per quella che non lo fa Stessa griglia, due esportazioni, nessuna ridigitazione Se la tua pipeline converte comunque Markdown in HTML, Markdown in HTML ti mostra esattamente cosa produce la conversione.
Tabelle di Markdown rispetto alle tabelle HTML
| considerazione | Tabella dei ribassi | Tabella HTML |
|---|---|---|
| Leggibilità della fonte | Alto - scansionabile come testo semplice | I tag bassi dominano il contenuto |
| Celle multi-linea | Solo tramite <br> |
Native, qualsiasi contenuto a blocchi |
| Cellule unite | non supportato | colspan e rowspan |
| Allineamento per colonna | Sì, tramite i due punti delimitatore | Sì, tramite CSS o attributi |
| Controllo dello stile | nessuno | Css completo |
| Supporto al renderer | Estensione GFM, diffusa ma non universale | Universale ovunque sia consentito l'HTML |
| Cordialità diffusa | Buono, una riga per riga | Scarso, molte linee per fila |
La regola pratica: usa Markdown finché non hai bisogno di una cella unita, di un elemento a blocco all'interno di una cella o di uno stile specifico, quindi passa quella tabella all'HTML e lascia stare il resto del documento La maggior parte dei renderer Markdown passa attraverso l'HTML grezzo, quindi mescolare i due in un unico file è normale.
Una nota sulla privacy
Le tabelle che le persone costruiscono sono spesso quelle che preferirebbero non caricare: prezzi non ancora annunciati, conteggio degli effettivi, parametri di riferimento interni, un client's dati incollati da un foglio di calcolo.
Il generatore è JavaScript lato client La griglia, il parser di importazione e ogni esecuzione di esportazione nella pagina, e nulla di ciò che incolli lascia la tua macchina Caricalo una volta e continua a funzionare offline Questo è lo stesso principio dietro tutto su Toolz.dev, e il ragionamento vale la pena di essere letto per intero nella guida su Privacy dei dati negli strumenti online. Se stai mettendo insieme un insieme più ampio di utilità basate su browser per il lavoro quotidiano, il Guida agli strumenti di codifica E il Toolkit per sviluppatori web copri cos'altro guadagna un segnalibro.
Consigli pratici
Mantieni l'intestazione corta. Con il riempimento, la cella più ampia in una colonna imposta la larghezza di ogni riga nella sorgente Un'intestazione dettagliata rende il file grezzo rumoroso senza alcun vantaggio di rendering.
Non temere l'output non aggiunto per i file generati. Se una tabella è scritta da uno script e non viene mai letta come sorgente, disattivare il riempimento e salvare i byte.
Ordina prima di incollare. Riordinare le righe con un clic della freccia alla volta va bene per cinque righe e noioso per cinquanta Ordina prima nel foglio di calcolo, quindi importa.
Guarda per la riga di intestazione vuota. Con & quot; Prima riga è header" spento, il generatore emette un'intestazione vuota sopra i tuoi dati, perché GFM non ha modo di esprimere una tabella senza intestazione Alcuni renderer mostrano che come una sottile riga vuota Se ti disturba, esporta HTML invece, che non ha bisogno di alcuna intestazione.
Controlla il risultato reso, non la fonte. La sorgente imbottita che sembra perfetta può comunque essere resa errata se la riga del delimitatore ha il numero sbagliato di celle Incolla nell'anteprima di qualunque piattaforma tu stia pubblicando prima di chiamarla terminata.
FAQ
Come creo una tabella in markdown?
Una tabella Markdown ha bisogno di una riga di intestazione, una riga di delimitatore di trattini e una riga per record, con celle separate da caratteri pipe Riempi la griglia nel generatore e lo strumento scrive quella sintassi per te, inclusa la riga di delimitatore e gli eventuali due punti di allineamento.
Come si allineano le colonne in una tabella di markdown?
L'allineamento è impostato con i due punti nella riga del delimitatore: i due punti a sinistra si allineano a sinistra, i due punti su entrambi i lati al centro e i due punti a destra si allineano a destra Scegliere un allineamento da un'intestazione di colonna nell'editor e il corretto posizionamento dei due punti viene generato automaticamente.
Posso convertire un intervallo di fogli Excel o Google in una tabella di markdown?
si. Copia le celle nel foglio di calcolo e incollale nel pannello di importazione. I fogli di calcolo posizionano il testo separato da tabulazioni negli appunti, che l'importatore rileva automaticamente e carica nella griglia.
Come faccio a inserire un carattere di pipe all'interno di una cella del tavolo?
Un tubo letterale deve essere sfuggito con una barra rovesciata o il renderer lo leggerà come un separatore di colonne Digitare il tubo normalmente nell'editor e il generatore sfugge nell'output per voi.
Una cella della tabella Markdown può contenere più righe?
Non con le nuove linee reali, perché le tabelle GFM sono rigorosamente di una riga per riga La soluzione alternativa abituale è un tag di interruzione di riga HTML all'interno della cella, che questo strumento inserisce automaticamente quando una cella che incolli contiene un'interruzione di riga.
Perché la mia tabella viene visualizzata come testo normale su GitHub?
La riga del delimitatore è quasi sempre la causa: deve essere la seconda riga e deve avere lo stesso numero di celle dell'intestazione Una riga vuota mancante prima della tabella può anche impedirne il rendering quando la tabella segue un paragrafo o si trova all'interno di un elenco.
Devo riempire le colonne in modo che la sorgente si allinei?
No. I renderer ignorano gli spazi extra, quindi una tabella non imbottita viene visualizzata in modo identico Esiste un imbottitura per gli esseri umani che leggono il file raw in un editor o in un diff. Spegnilo con l'interruttore di output imbottito se preferisci la sorgente compatta.
Le tabelle Markdown sono supportate ovunque?
Le tabelle sono un'estensione GitHub Flavored Markdown piuttosto che parte della specifica CommonMark originale GitHub, GitLab, Obsidian, Notion, Docusaurus e la maggior parte dei generatori di siti statici li supportano, ma alcuni renderer minimi no. Passa l'output all'HTML se il tuo è uno di questi.
