Generatore tabelle Markdown

Informazioni sulle tabelle Markdown

Le tabelle Markdown usano barre verticali (|) e trattini (-) per creare dati tabulari strutturati in testo semplice. Sono supportate da GitHub, GitLab, Reddit e dalla maggior parte dei renderer Markdown. La riga di allineamento usa i due punti per indicare un allineamento a sinistra, al centro o a destra per ogni colonna.

Scrivere tabelle Markdown a mano può essere noioso e soggetto a errori. Questo editor visivo ti permette di inserire dati in una griglia in stile foglio di calcolo e genera Markdown correttamente formattato in tempo reale. Tutta l'elaborazione avviene nel tuo browser.

La sintassi delle tabelle a pipe, meccanicamente

Una tabella GFM consiste di tre parti: una riga di intestazione con celle separate da pipe (|), una riga delimitatore immediatamente sotto che usa trattini (---) per ogni colonna, e zero o più righe di dati con la stessa struttura separata da pipe. Pipe iniziali e finali su ogni riga sono opzionali ma convenzionalmente inclusi per la leggibilità. L'allineamento della colonna è specificato dai due punti nella riga delimitatore: :--- per allineamento a sinistra (il default), :---: per centro, ---: per destra. La tabella minima funzionante appare così nel sorgente: | Intestazione | Intestazione | sulla riga 1, | --- | --- | sulla riga 2, | Cella | Cella | dalla riga 3 in poi. Il contenuto della cella può includere qualsiasi formattazione Markdown inline (grassetto, corsivo, link, span di codice, immagini) ma non può includere elementi di livello block (liste, blocchi di codice, blockquote). Le interruzioni di riga all'interno di una cella devono essere codificate come tag <br> piuttosto che newline letterali, poiché i newline letterali romperebbero la struttura della tabella. I caratteri pipe all'interno del contenuto della cella devono essere escapati come \|, altrimenti il parser li tratta come separatori di colonna e il conteggio delle colonne della riga va male. La maggior parte dei parser tollera larghezze di colonna disallineate; il sorgente | a | b | e | aaa | b | renderizzano in modo identico, anche se quest'ultimo sembra più "giusto" nel sorgente. Questo strumento emette sempre sorgente con larghezza allineata per leggibilità, ma renderizza come il sorgente compatto.

Dove le tabelle renderizzano e dove no

Renderizza correttamente: GitHub (issue, pull request, README, pagine wiki, discussioni, code review, commenti ovunque), GitLab (stesse superfici), Bitbucket, Stack Overflow, Reddit (quando GFM è abilitato nel subreddit, che è la maggior parte), Discord (solo in contesto di blocco codice, le tabelle GFM complete non renderizzano nei messaggi di chat ma markdown-it le processa nella superficie docs), Notion (con la sua importazione di tabelle), Obsidian, Logseq, Bear, la maggior parte dei generatori di siti statici (Hugo, Jekyll, Eleventy, Astro con il plugin remark-gfm, Next.js MDX), l'anteprima di VS Code, GitHub Pages, Read the Docs (a seconda della configurazione). Non renderizza correttamente: CommonMark stretto (Pandoc con il reader commonmark e nessuna estensione, parser Discount C senza il flag pipe-table), Slack (renderizza un subset di Markdown ma non le tabelle), la maggior parte dei client email (l'HTML renderizzato in email è strutturalmente buono ma con stile inline, non Markdown), installazioni più vecchie di WordPress senza un plugin Markdown. La regola generale: se la tua destinazione è una piattaforma orientata agli sviluppatori (famiglia GitHub, documentazione tecnica), le tabelle GFM funzionano. Se la tua destinazione è una piattaforma per un pubblico generale (Slack, email, Twitter), assumi che le tabelle non renderizzeranno e o pre-renderizzale a un'immagine o riscrivi come una lista.

Sintassi alternative per tabelle Markdown

Il formato delle tabelle a pipe domina grazie alla portata di GitHub, ma non è l'unica sintassi di tabella Markdown. Le tabelle semplici di Pandoc usano separatori di righe vuote e trattini e allineano le colonne per posizione visiva piuttosto che per pipe, molto più leggibili per tabelle strette ma più difficili da scrivere a mano. Le tabelle multi-riga di Pandoc supportano celle che si estendono su più righe, importanti per contenuto descrittivo lungo che non entra in una riga. Le tabelle a griglia di Pandoc usano bordi ASCII-art (+---+---+) che sembrano dolorosi da mantenere a mano ma sono facili per gli strumenti da emettere. reStructuredText (Sphinx) usa esclusivamente tabelle a griglia, la documentazione di ogni progetto Python è scritta in questo modo. AsciiDoc usa una sintassi diversa con prefisso pipe (|===) ottimizzata per la scrittura di libri tecnici. HTML in Markdown è sempre disponibile come via di fuga: qualsiasi processore Markdown passa HTML grezzo attraverso, quindi quando le tabelle a pipe non bastano puoi inserire una vera <table> con span completo di righe/colonne, markup semantico e stile CSS. La sintassi delle tabelle a pipe che questo strumento genera è in stile GFM, la scelta più compatibile per l'ecosistema moderno degli sviluppatori.

Usi comuni

• File README di GitHub. Tabelle di confronto ("la nostra libreria vs alternative"), matrici di funzionalità, liste di versioni supportate, liste di contributor, schede di riferimento dei comandi. Probabilmente l'uso di produzione singolo più comune delle tabelle GFM.
• Documentazione e wiki. Tabelle di riferimento API (nome parametro / tipo / descrizione / default), tabelle di opzioni di configurazione, riferimenti di codici di errore, matrici di traduzione linguistica. Read the Docs, MkDocs, Docusaurus, GitBook supportano tutti le tabelle GFM.
• Post di blog di confronto. Articoli "Framework X vs Framework Y", confronti di specifiche hardware, suddivisioni di livelli di prezzo. Il formato delle tabelle a pipe è molto più leggibile dei paragrafi ad-hoc e renderizza in modo pulito su Medium, dev.to, Substack e blog personali.
• Pagine di prezzi. Le tabelle dei livelli SaaS (Free / Pro / Enterprise attraverso righe di funzionalità) funzionano bene in forma di tabella a pipe per mockup rapidi in versione bozza prima che i designer commerciali facciano la versione HTML rifinita.
• Template di issue GitHub. I template di segnalazione bug spesso includono passi di riproduzione in forma di tabella (Passo / Atteso / Effettivo / Screenshot). Tabelle di stato della project board per tracciare i progressi dello sprint.
• Note di riunione e piani di progetto. Tabelle di action item (Proprietario / Azione / Data scadenza / Stato) in documenti di note condivise. Log delle decisioni. Registri dei rischi.
• Importazione CSV. Molti generatori di tabelle offrono l'importazione CSV-a-Markdown, incolla un CSV, ottieni una tabella Markdown. Il contrario (Markdown a CSV) è anche comune quando si estraggono dati strutturati dalla documentazione di nuovo in formato foglio di calcolo.

Il problema della larghezza e altri vincoli

Le tabelle a pipe hanno diverse limitazioni inerenti che vale la pena conoscere. La larghezza della colonna è vincolata dal contenuto della cella più lungo, un URL lungo o un paragrafo descrittivo in una cella forza l'intera colonna ad essere larga, il che può produrre tabelle ingombranti che non si adattano alle larghezze standard delle pagine di documentazione. La correzione è o troncare il contenuto lungo (collegando altrove per i dettagli) o usare HTML inline se hai bisogno di celle a capo. Nessuno span di riga o colonna, ogni cella occupa esattamente una riga e una colonna. Tabelle complesse con celle unite necessitano di vera <table> HTML con attributi rowspan / colspan. Nessuna tabella annidata, non puoi mettere una tabella all'interno di un'altra cella di tabella in Markdown. Nessun contenuto di livello block nelle celle, nessuna lista, nessun blocco di codice, nessun blockquote all'interno di una cella. Il contenuto inline (grassetto, corsivo, span di codice, link, immagini) va bene ma qualsiasi cosa multi-riga necessita di tag <br>. La riga di intestazione è obbligatoria in GFM, non c'è sintassi di tabella senza intestazione. Se vuoi una tabella senza intestazione visibile, lascia le celle di intestazione vuote ma la riga deve comunque essere presente. L'allineamento si applica per-colonna all'intera colonna, non puoi avere allineamento diverso per celle diverse nella stessa colonna. Per layout di tabella sofisticati che superano questi vincoli, lo strumento giusto è HTML nel tuo sorgente Markdown, non Markdown stesso.

Conversione CSV verso e da Markdown

La maggior parte dei dati tabulari del mondo reale vive in file CSV (esportazioni di fogli di calcolo, risposte API, output di analisi log), convertire verso e da Markdown è un flusso di lavoro comune. CSV verso Markdown: parsa il CSV (gestendo campi tra virgolette con virgole incorporate, virgolette escapate, interruzioni di riga all'interno dei campi), poi formatta ogni riga come | valore | valore | con le righe di intestazione e delimitatore appropriate. La maggior parte dei generatori di tabelle inclusi questo offrono l'importazione CSV; per conversioni una tantum puoi anche usare lo strumento da riga di comando csvlook di csvkit che produce un output simile in formato pipe. Markdown verso CSV: parsa la tabella GFM di nuovo in righe e colonne, poi emetti CSV con quotatura appropriata. Utile quando si estraggono dati strutturati dalla documentazione di nuovo in forma di foglio di calcolo per l'analisi. La direzione Markdown-a-CSV è offerta da strumenti come pandoc (con la combinazione reader/writer giusta), tableconvert.com e varie utility da riga di comando. Il round-trip è lossy in una direzione, la formattazione (grassetto, link, immagini) sopravvive al passaggio CSV intatta solo se scrivi il contenuto della cella CSV come testo Markdown grezzo e tratti di nuovo il risultato come Markdown.

Privacy: perché il solo-browser conta anche qui

Le tabelle non sembrano dati sensibili, ma i contenuti delle tabelle spesso lo sono. I piani di progetto contengono decisioni del personale e funzionalità non annunciate. Le tabelle di prezzi contengono informazioni commerciali. Le tabelle di confronto in post di blog non pubblicati rivelano il posizionamento editoriale. Gli action item delle note di riunione contengono informazioni di assegnazione e responsabilità. I generatori di tabelle lato server caricano i tuoi dati su una terza parte dove rimangono nei log. Questo strumento gira interamente nel tuo browser tramite JavaScript, verifica nel tab Network di DevTools mentre modifichi le celle, o porta la pagina offline (modalità aereo) dopo che si carica e l'editor funziona ancora. Sicuro per bozze di documentazione non pubblicate, pianificazione interna di progetto, tabelle di confronto per post di blog non ancora pubblicati o qualsiasi contenuto di tabella che non vorresti copiato sull'hard drive di uno sconosciuto.

Domande frequenti

Quale sintassi di tabella Markdown viene generata?

Genera la sintassi standard GFM (GitHub Flavored Markdown) con barre verticali, una riga di separazione di trattini e due punti opzionali per l'allineamento. Questa sintassi funziona su GitHub, GitLab, Reddit, Jekyll, Hugo e sulla maggior parte dei processori Markdown.

Come definire l'allineamento delle colonne?

Clicca sui pulsanti L (sinistra), C (centro) o R (destra) sotto ogni intestazione di colonna. L'allineamento a sinistra usa :---, il centro :---: e la destra ---: nella riga di separazione.

Posso importare da CSV o incollare da un foglio di calcolo?

L'importazione CSV è nella roadmap. Per ora, incollare-da-Excel/Google Sheets funziona spesso perché la maggior parte delle app di foglio di calcolo mette dati separati da tab nella clipboard, che puoi incollare in celle individuali. Per importazione CSV in blocco senza incollaggio manuale, strumenti da riga di comando come csvlook di csvkit producono output simile in formato tabella GFM, o pandoc può convertire CSV in Markdown direttamente con pandoc --from csv --to gfm input.csv.

E le celle unite, le tabelle annidate o il contenuto block nelle celle?

Le tabelle a pipe GFM non le supportano. Ogni cella occupa esattamente una riga e una colonna; nessun rowspan o colspan. Nessuna tabella annidata. Nessun contenuto di livello block (liste, blocchi di codice, blockquote) all'interno di una cella, solo contenuto inline (grassetto, corsivo, span di codice, link, immagini, interruzioni di riga tramite <br>). Per layout di tabella sofisticati che superano questi vincoli, incorpora HTML <table> grezzo direttamente nel tuo sorgente Markdown, ogni processore Markdown passa HTML attraverso invariato. Il compromesso è che il sorgente diventa molto più difficile da leggere e modificare a mano.

C'è un limite di righe o colonne?

Puoi avere fino a 20 colonne e 100 righe. Per la maggior parte della documentazione e dei file README, è più che sufficiente. La tabella si aggiorna in tempo reale mentre digiti.

I contenuti della mia tabella vengono inviati da qualche parte?

No. La generazione gira interamente nel tuo browser tramite JavaScript. Le celle che modifichi e l'output Markdown non attraversano mai la rete, verifica nel tab Network di DevTools mentre digiti, o porta la pagina offline (modalità aereo) dopo che si carica e l'editor funziona ancora. Sicuro per bozze di documentazione non pubblicate, piani di progetto interni, tabelle di confronto prezzi non ancora pubblicate, o qualsiasi contenuto tabulare che non vorresti copiato sull'hard drive di uno sconosciuto.

Strumenti correlati