Come utilizzare rapidamente Markdown su GitHub e Reddit

Informatec Digital » Risorse » Come utilizzare rapidamente Markdown su GitHub e Reddit

Se scrivi spesso su GitHub o passi molto tempo su Reddit, padroneggiare Markdown è una di quelle cose che ti farà risparmiare ore e ti semplificherà la vita. È un linguaggio di markup molto leggero che ti permette di formattare rapidamente il testo semplice senza doverti sforzare con menu o pulsanti, semplicemente posizionando pochi simboli nei punti giusti.

Su GitHub lo troverete ovunque: nei file README.md dei repository , nelle issue, nelle pull request, nelle discussioni e persino nel vostro profilo. Reddit, invece, utilizza una variante chiamata Snoomark (Markdown in stile Reddit) che eredita gran parte della sintassi di GitHub, con alcune caratteristiche e limitazioni uniche. Vediamo, passo dopo passo e con molti esempi, come usare Markdown su GitHub e Reddit in modo rapido e senza perdere nulla di importante.

Cos'è Markdown e perché è così utile su GitHub e Reddit?

Markdown è un linguaggio di markup leggero progettato per rendere il testo semplice facile da leggere e scrivere, consentendo al contempo una conversione agevole in HTML. In pratica, ciò significa che è possibile scrivere testo normale e aggiungere alcuni caratteri speciali per creare titoli, elenchi, tabelle, citazioni, codice formattato, link o immagini.

Su GitHub, l'implementazione utilizzata è GitHub Flavored Markdown (GFM), che estende la sintassi classica con tabelle, elenchi di cose da fare, evidenziazione avanzata del codice, supporto per i colori, avvisi e alcuni tag HTML consentiti. Tutto ciò viene automaticamente renderizzato nei file .md e nei campi dei commenti della piattaforma.

Reddit utilizza un proprio editor chiamato Snoomark, derivato da GFM. Condivide gran parte delle funzionalità di base (grassetto, corsivo, titoli, elenchi, citazioni, codice in linea o a blocchi, link, ecc.), ma presenta importanti peculiarità : ad esempio, il supporto per le immagini è più limitato a seconda del contesto e aggiunge elementi proprietari come gli spoiler.

Il bello di tutto questo è che, con un'unica sintassi, puoi scrivere testi che abbiano un bell'aspetto sia su GitHub che su Reddit, adattando solo pochi dettagli laddove ogni piattaforma funziona diversamente. Imparare le regole di base ti permette di navigare facilmente su entrambe le piattaforme senza dover reimparare nulla da zero.

Intestazioni e struttura dei contenuti

Una delle prime cose che userai sono i titoli , sia su GitHub che su Reddit. Aiutano a strutturare il testo in sezioni e sottosezioni.

In Markdown, un'intestazione viene creata anteponendo al testo da uno a sei simboli di cancelletto: uno per un'intestazione di livello 1, due per il livello 2 e così via fino al livello 6. Ad esempio, in un file README.md di GitHub potresti avere qualcosa del genere: # Titolo principale , ## Sezione , ### Sottosezione , ecc.

Quando GitHub rileva due o più intestazioni in un file, genera automaticamente un indice accessibile tramite l'icona "Struttura" nella parte superiore del file. Ogni intestazione viene visualizzata come un collegamento che rimanda direttamente alla sezione corrispondente, una soluzione ideale per documenti lunghi.

Inoltre, ogni titolo diventa un'ancora interna a cui è possibile collegarsi tramite un frammento di URL basato sul testo del titolo. Per generare tale frammento, GitHub applica regole ben precise: converte le lettere in minuscolo, sostituisce gli spazi con trattini, rimuove la punteggiatura e i caratteri di formattazione (come il corsivo), elimina gli spazi in eccesso e, se il risultato corrisponde a un altro titolo precedente, aggiunge un suffisso numerico (-1, -2, ecc.) per renderlo univoco.

Questo permette di fare cose come inserire una ## Sezione di esempio e poi collegarla da un altro punto del documento con un link come (#sezione-di-esempio) , o persino collegarsi a sezioni con caratteri speciali nel titolo, poiché GitHub genera lo snippet seguendo tali regole e lo rende accessibile con lo stesso schema.

Enfasi, testo evidenziato e citazioni

Markdown permette di evidenziare il testo utilizzando varie forme di enfasi : grassetto, corsivo, barrato, pedice, apice o sottolineato. Su GitHub, la tabella di stile tipica si presenterebbe più o meno così, anche se qui l'abbiamo riassunta in termini diversi:

Per rendere il testo in grassetto , racchiudilo tra doppi asterischi o doppi trattini bassi; per il corsivo, usa un singolo asterisco o un singolo trattino basso; per barrarlo, usa una doppia tilde (due tilde) su entrambi i lati del testo. Puoi anche combinare grassetto e corsivo annidati, usare tre asterischi per applicarli entrambi a un'intera sezione di testo, oppure usare tag HTML come `<b>` _{per ^{pedici e apici e `<i>` per la sottolineatura.}}

GitHub permette anche di creare citazioni a blocco inserendo il simbolo "maggiore di" (>) all'inizio della riga. Il testo citato viene visualizzato con una barra verticale a sinistra e in grigio, in modo da risaltare chiaramente. È possibile inserire più righe all'interno dello stesso blocco di citazione e persino annidare le citazioni aggiungendo altri simboli ">" all'inizio.

Una forma avanzata di citazione, esclusiva di GitHub, è l' avviso o ammonimento . Utilizza la stessa sintassi del blocco di citazione, ma la prima riga include un marcatore speciale per indicare il tipo di avviso. Ad esempio, è possibile specificare `alert` per informazioni utili, `suggerimenti utili`, `dati chiave`, `avvisi urgenti` e `avvisi di rischi o conseguenze negative`. GitHub visualizza ogni tipo con un colore e un'icona diversi, contribuendo a evidenziare le informazioni critiche nella documentazione.

Anche Reddit supporta le citazioni semplici con lo stesso simbolo >, sebbene non disponga del ricco sistema di ping di GitHub. Ciononostante, rimane un modo molto utile per rispondere a qualcuno citando parte del suo messaggio senza ripeterlo per intero.

Evidenziazione del codice, blocchi e colori

Sia GitHub che Reddit consentono di evidenziare frammenti di codice all'interno del testo utilizzando gli apici inversi. Per il codice inline, si racchiude la parola o il comando tra due apici inversi. Questo è ideale per evidenziare, ad esempio, ` git status` all'interno di una frase, rendendo chiaro che si tratta di un comando.

Quando si desidera un blocco di codice autonomo, Markdown utilizza tre apici inversi: si scrive una riga con tre apici inversi, poi il codice su righe separate e si chiude con altri tre apici inversi. Su GitHub, se si specifica anche il linguaggio subito dopo i primi apici inversi, viene applicata l'evidenziazione della sintassi con colori e formattazione specifici per quel linguaggio.

GitHub offre anche una funzionalità specifica per evidenziare i valori di colore tra apici inversi. Se si digita un colore in formato esadecimale, RGB o HSL tra apici inversi, la piattaforma include un piccolo indicatore di colore accanto al testo. Ad esempio, se il colore di sfondo in modalità chiara è #ffffff e in modalità scura è #000000, l'evidenziazione di questi codici consente di distinguere rapidamente i due valori.

Per quanto riguarda la visualizzazione del codice e delle tabelle, GitHub consente di abilitare un carattere a spaziatura fissa in tutti i campi dei commenti, facilitando la gestione di testi tecnici. Se modificate spesso frammenti di codice nel browser o in editor come Visual Studio Code , l'attivazione di questa opzione renderà l'allineamento e la leggibilità molto più uniformi.

Reddit supporta anche blocchi di codice con apici inversi, sia in linea che all'interno di blocchi, sebbene il loro utilizzo sia più focalizzato su piccoli frammenti o pseudocodice che su documentazione estesa come quella di un repository.

Collegamenti, ancore e navigazione interna

Creare link in Markdown è molto semplice: basta racchiudere il testo da mostrare all'utente tra parentesi quadre e l'URL tra parentesi tonde. Questo metodo funziona sia su GitHub che su Reddit e può essere ulteriormente migliorato con le scorciatoie da tastiera su GitHub (ad esempio, utilizzando combinazioni di tasti per convertire rapidamente il testo selezionato in un link).

GitHub aggiunge alcune funzionalità extra relative alla navigazione. Innanzitutto, consente di creare link diretti alle intestazioni utilizzando le regole di generazione degli snippet discusse in precedenza. In secondo luogo, supporta i link relativi all'interno del repository stesso, il che è fondamentale per la documentazione tecnica.

Un collegamento relativo è un collegamento calcolato utilizzando il file corrente come riferimento. Ad esempio, se il tuo file README si trova nella directory principale del progetto e vuoi creare un collegamento al file docs/CONTRIBUTING.md, ti basterà scrivere un collegamento con il percorso docs/CONTRIBUTING.md. GitHub si occuperà di tradurre correttamente questo collegamento relativo in qualsiasi ramo ti trovi, impedendo che si interrompa quando cambi ramo o cloni il repository.

Si consiglia di utilizzare sempre percorsi relativi quando si naviga tra i file all'interno dello stesso repository, poiché i collegamenti assoluti potrebbero smettere di funzionare in cloni o fork. GitHub consente l'utilizzo di operatori standard come ./ o ../ e percorsi che iniziano con / relativi alla directory principale del progetto.

Se desideri creare punti di ancoraggio personalizzati all'interno di un documento, oltre alle intestazioni, puoi utilizzare i tag HTML con l'attributo `name`. Questo ti consente di posizionare un punto di destinazione al centro di un paragrafo o accanto a un testo che non ha un titolo proprio e di collegarlo utilizzando la stessa sintassi delle intestazioni generate automaticamente.

Immagini su GitHub: Markdown, HTML e percorsi relativi

Su GitHub, le immagini vengono generalmente incorporate utilizzando la stessa sintassi dei link, ma precedute da un punto esclamativo. Il testo alternativo (alt) è specificato tra parentesi quadre e l'URL o il percorso dell'immagine è racchiuso tra parentesi tonde. Questo testo alternativo è importante per l'accessibilità , poiché è ciò che i lettori di schermo leggeranno e ciò che verrà visualizzato se l'immagine non viene caricata.

Le immagini possono provenire da file all'interno del repository stesso o da URL esterni. GitHub consente diversi modelli di percorso relativi per caricare immagini da rami diversi, altri repository o persino problemi e commenti, utilizzando suffissi come ?raw=true per forzare il download diretto del file quando necessario.

Oltre alla sintassi Markdown standard, GitHub supporta l'utilizzo dell'elemento HTML `<picture>`. Questo elemento è particolarmente utile per caricare immagini responsive che cambiano in base alle preferenze del tema dell'utente (chiaro o scuro). Utilizzando la media query `prefers-color-scheme`, è possibile definire diverse sorgenti di immagini per ciascuna modalità e un'immagine predefinita per i browser che non supportano questa funzionalità.

Il modello tipico prevede l'inclusione all'interno diversi elementi con i suoi attributi media e srcset e infine un Utilizzando l'attributo alt e un URL generico, gli utenti in modalità scura visualizzano un'immagine adattata, mentre quelli in modalità chiara ne ricevono una diversa, senza dover duplicare il contenuto nel file README.

GitHub supporta anche i commenti HTML nei file Markdown, consentendo di aggiungere promemoria invisibili al lettore, ad esempio per ricordargli di aggiornare una sezione con immagini o di aggiungere nuovi esempi in seguito.

Tabelle, sezioni pieghevoli e separazione dei contenuti

Uno dei miglioramenti più utili di GitHub Flavored Markdown è il supporto per le tabelle . È possibile organizzare i dati in righe e colonne utilizzando barre verticali per separare le celle e una riga di trattini per contrassegnare l'intestazione. È anche possibile allineare le colonne a destra, a sinistra o al centro utilizzando i due punti nella riga di separazione.

Le tabelle sono molto utili per presentare elenchi di linguaggi di programmazione, framework utilizzati, attività pianificate, confronti tra funzionalità o qualsiasi altra informazione che tragga vantaggio da una struttura a matrice. GitHub visualizza queste tabelle con uno stile pulito e leggibile.

Per organizzare un file README lungo, è possibile utilizzare il tag HTML `<details>` per creare sezioni comprimibili. Queste sezioni visualizzano un riepilogo all'interno del tag `<summary>` e consentono all'utente di espandere o comprimere il contenuto aggiuntivo a seconda delle necessità. È prassi comune racchiudere tabelle o blocchi di informazioni secondarie all'interno di `<details>` per evitare di sovraccaricare l'utente a prima vista.

Se desideri che la sezione appaia espansa per impostazione predefinita, aggiungi semplicemente l'attributo open a Questa tecnica è molto pratica per raggruppare classifiche, elenchi lunghi o contenuti che non sono essenziali per una prima lettura ma che è comodo avere a portata di mano.

Un altro semplice strumento per organizzare le informazioni è la riga orizzontale. Si crea tracciando tre o più trattini su una linea e serve a delimitare le sezioni, permettendo di separare chiaramente, ad esempio, una sezione descrittiva da una sezione di riferimenti o note aggiuntive.

Queste regole possono essere combinate con citazioni a fine documento per evidenziare frasi ispiratrici, promemoria o messaggi chiave. Un esempio tipico potrebbe essere l'inserimento di una citazione motivazionale alla fine del file README del profilo, formattata con un blocco di citazione dopo una riga di separazione.

Commenti nascosti e controllo della formattazione

GitHub permette di inserire commenti HTML all'interno di Markdown utilizzando la sintassi <!-- commento -->. Tutto ciò che viene inserito all'interno di questo commento non verrà visualizzato nel contenuto renderizzato, ma sarà visibile nel codice sorgente, risultando ideale per note interne o elenchi di cose da fare.

Ad esempio, nel file README di un profilo è possibile aggiungere un commento che indichi la necessità di ampliare la sezione "Informazioni su di me" in seguito, oppure la necessità di rivedere una tabella delle tecnologie obsolete, senza che chi visita il profilo possa visualizzarlo direttamente.

Un'altra utile funzionalità è la possibilità di eseguire l'escape dei caratteri che normalmente verrebbero interpretati come Markdown. Se è necessario visualizzare asterischi, simboli di cancelletto o altri simboli letteralmente, senza formattarli, è sufficiente far precedere ciascuno di essi da una barra rovesciata. Questo permette, ad esempio, di scrivere espressioni che includono simboli di elenco senza convertirli in elenchi veri e propri.

Quando visualizzi un file di markup su GitHub, hai la possibilità di passare dalla visualizzazione renderizzata al codice sorgente tramite un pulsante in alto (oppure di aprirlo in editor come Brackets ). Disabilitando l'interpretazione del Markdown, puoi accedere alle tipiche funzionalità di visualizzazione del codice, come il collegamento a righe specifiche , molto utile quando si desidera evidenziare una sezione precisa di un file README o di qualsiasi file .md.

Infine, ricorda che GitHub gestisce le interruzioni di riga in modo diverso nei commenti (issue, PR, ecc.) e nei file .md. Nei commenti, le interruzioni di riga vengono rispettate direttamente, mentre nei file Markdown è necessario aggiungere due spazi alla fine della riga, una barra rovesciata o un punto. per forzare il salto all'interno dello stesso paragrafo.

Liste, liste annidate e liste di cose da fare

Gli elenchi sono uno degli elementi più utilizzati in Markdown, sia su GitHub che su Reddit. È possibile creare elenchi non ordinati anteponendo a ciascun elemento un trattino, un asterisco o un segno più. Tutti questi marcatori vengono visualizzati in modo simile agli elenchi puntati.

Per generare elenchi ordinati , numera ogni riga con un numero seguito da un punto e uno spazio. Sebbene l'ordine dei numeri non debba essere perfetto (GitHub di solito lo ricalcola), è consigliabile mantenere una numerazione coerente per rendere il codice sorgente più leggibile.

Gli elenchi annidati si creano semplicemente rientrando gli elementi sottostanti. Negli editor a spaziatura fissa come Sublime Text , è sufficiente allineare visivamente i marcatori degli elenchi annidati sotto il primo carattere del testo dell'elemento principale. In contesti come l'editor dei commenti di GitHub, dove il carattere non è a spaziatura fissa, è necessario contare quanti caratteri precedono il testo e utilizzare quel numero di spazi per la rientranza.

È possibile creare anche più livelli di annidamento, purché si mantenga costante il numero di spazi. Per elenchi molto complessi, questo sistema richiede un po' di pratica, ma una volta capito il meccanismo, è molto veloce da applicare.

GitHub offre anche elenchi di attività , molto utili per segnalazioni di problemi, richieste di pull e documentazione. Questi elenchi si creano anteponendo al nome dell'elenco un trattino, uno spazio e una coppia di parentesi quadre con uno spazio o una "x" all'interno: una per le attività in sospeso e una per le attività completate. Gli elenchi vengono visualizzati con caselle di controllo che possono essere selezionate o deselezionate dall'interfaccia.

Se il testo di un elemento della lista delle cose da fare inizia con le parentesi, è necessario anteporre una barra rovesciata per evitare confusione nel parser. È un piccolo dettaglio, ma importante quando si scrivono descrizioni che iniziano con qualcosa come "(Opzionale)" o simili.

Menzioni, riferimenti ed emoji su GitHub

Uno dei vantaggi di scrivere in Markdown su GitHub è la possibilità di menzionare direttamente utenti e team sulla piattaforma. Basta digitare @ seguito dal nome utente o dal nome del team e GitHub invierà una notifica a quell'account, richiamando la loro attenzione sulla conversazione.

Quando digiti il ​​simbolo @, GitHub visualizza un elenco di utenti e team associati al repository o al thread, e puoi filtrare questo elenco mentre digiti. Usa i tasti freccia e premi Invio o Tab per accettare i suggerimenti. Per i team, usa il formato @organizzazione/nome-team e tutti i membri del team verranno iscritti al thread.

Oltre alle menzioni, GitHub semplifica la consultazione di problemi e richieste di pull semplicemente digitando # seguito da un numero o da una parte del titolo. Appare un elenco di risultati suggeriti, che è possibile completare nello stesso modo delle menzioni. Questo velocizza notevolmente la navigazione tra le conversazioni correlate.

Se il repository dispone di riferimenti con collegamento automatico personalizzato, alcune notazioni esterne (come gli ID dei ticket JIRA o Zendesk) potrebbero essere convertite automaticamente in link brevi. Questa impostazione richiede privilegi amministrativi, ma una volta abilitata, consente la condivisione dei dati tra sistemi con il minimo sforzo.

Infine, GitHub supporta le emoji tramite codice: digita due punti, seguiti dal nome dell'emoji e termina con altri due punti. Mentre inizi a digitare, appare un elenco di suggerimenti, che puoi accettare premendo Tab o Invio. L'inserimento di emoji nei commenti contribuisce a dare loro un tocco più personale, a patto di non abusarne nella documentazione formale.

Note a piè di pagina e contenuti avanzati

GitHub supporta anche le note a piè di pagina utilizzando una sintassi basata su parentesi quadre e un identificatore con il carattere accento circonflesso. Nel punto in cui si desidera inserire il riferimento, si inserisce qualcosa come `<footnote>`, e alla fine del documento si definisce il testo della nota a piè di pagina con lo stesso tag, seguito da due punti e dal contenuto.

Le note a piè di pagina possono estendersi su più righe e, per forzare un'interruzione di riga all'interno di una nota, si utilizzano doppi spazi alla fine della riga, proprio come nel corpo principale del Markdown. Durante il rendering, GitHub visualizza un apice sul testo e un elenco di note a piè di pagina alla fine, con collegamenti per navigare tra riferimenti e note.

Un'altra funzionalità avanzata offerta da GitHub sono gli avvisi già menzionati (NOTA, SUGGERIMENTO, IMPORTANTE, AVVERTENZA e ATTENZIONE). Si consiglia di utilizzarli solo quando strettamente necessario ed evitare di concatenarne troppi per non sovraccaricare il lettore. Non possono essere annidati all'interno di altri elementi complessi, quindi è fondamentale pianificarne attentamente il posizionamento.

Infine, è possibile chiedere a GitHub di nascondere temporaneamente sezioni di Markdown renderizzato racchiudendole in commenti HTML, oppure di ignorare l'elaborazione di determinati caratteri con la barra rovesciata. Questo è particolarmente utile quando si documenta la sintassi Markdown stessa e si ha bisogno di mostrare esempi così come sono, senza interpretazione.

Markdown su Reddit: Snoomark e modalità di modifica

Reddit è una piattaforma di discussione in cui sono benvenuti quasi tutti gli argomenti, organizzati in subreddit. Per quanto riguarda la formattazione, offre due editor: uno per il testo formattato, più visivo, e un altro per il testo semplice basato su Markdown. Se si desidera lavorare velocemente e avere un controllo preciso sul risultato, è consigliabile utilizzare l'opzione Markdown.

Di default, Reddit attiva l'editor di testo avanzato, quindi per passare alla modalità markup devi cliccare sull'opzione " Modalità Markdown" all'interno della casella di testo di un post o di un commento. Da lì, puoi utilizzare direttamente la sintassi di Snoomark.

Se preferisci che l'editor Markdown si carichi sempre, vai alle tue impostazioni utente, accedi alla sezione Impostazioni feed e abilita l' opzione "Imposta Markdown come predefinito" . In questo modo, l'editor Markdown si aprirà automaticamente ogni volta che inizi a scrivere un post o un commento, senza che tu debba modificarlo manualmente.

Reddit supporta la maggior parte delle funzionalità Markdown, sia di base che avanzate: titoli, grassetto e corsivo, elenchi, citazioni, blocchi di codice, link e alcune funzionalità proprietarie come gli spoiler. Tuttavia, presenta notevoli lacune rispetto a GitHub, soprattutto nella gestione delle immagini , che dipende fortemente dal contesto e dal tipo di editor.

Sintassi supportata da Reddit e spoiler

La variante di Snoomark utilizzata da Reddit include molti elementi in comune con GitHub, quindi se hai già familiarità con Markdown per i repository, trasferire queste conoscenze all'ambiente Reddit è piuttosto semplice. Puoi usare titoli per strutturare post lunghi, elenchi numerati o puntati, citazioni per rispondere ad altri utenti e blocchi di codice quando vuoi visualizzare comandi o frammenti tecnici.

Una delle differenze più evidenti riguarda la gestione delle immagini su Reddit . Sebbene in molti casi le immagini vengano caricate tramite l'interfaccia grafica e non direttamente con la sintassi Markdown, il motore che elabora il contenuto testuale è comunque Snoomark, quindi la formattazione che circonda le immagini si basa effettivamente su Markdown.

Reddit, d'altro canto, aggiunge funzionalità extra non incluse nelle specifiche standard, come gli spoiler. Questi permettono di nascondere il testo dietro un livello che l'utente può rivelare con un clic. Tecnicamente, quando Reddit elabora uno spoiler, lo trasforma in una combinazione di HTML, classi CSS e JavaScript specifico della piattaforma.

La rappresentazione HTML risultante di uno spoiler include gestori che controllano quando mostrare o nascondere il contenuto e, sebbene in teoria qualcosa di simile potrebbe essere scritto con semplice HTML, su Reddit dipende dalla sua implementazione interna. La cosa importante per te come utente è che, quando scrivi, devi solo usare la sintassi specifica per gli spoiler fornita dall'editor e Snoomark si occuperà di tradurla nella struttura appropriata.

In breve, Snoomark eredita molte caratteristiche da GitHub Flavored Markdown, ma è orientato alle esigenze di una community di discussione piuttosto che alla documentazione di progetto. Ciononostante, il nucleo rimane lo stesso: testo semplice con simboli basilari trasformato in contenuti strutturati e leggibili.

Padroneggiare la sintassi Markdown su GitHub e Reddit rende molto più efficiente la scrittura di documentazione tecnica, l'apertura di segnalazioni di problemi ben spiegate, l'inserimento di commenti chiari sulle pull request e la partecipazione alle discussioni su Reddit. Con poche regole fondamentali (intestazioni, enfasi, elenchi, citazioni, blocchi di codice, link, immagini e accorgimenti specifici come tabelle, dettagli a scomparsa, avvisi, note a piè di pagina e spoiler) è possibile passare da messaggi banali a contenuti chiari, facilmente leggibili e professionali senza dover cliccare un solo pulsante del mouse.