Com utilitzar Markdown a GitHub i Reddit de forma ràpida

Informatec Digital » Recursos » Com utilitzar Markdown a GitHub i Reddit de forma ràpida

Si sols escriure a GitHub o passes força temps a Reddit, dominar Markdown és una d'aquelles coses que t'estalvien hores i et fan la vida més fàcil. És un llenguatge de marcat molt lleuger que et permet donar format a un text pla de forma ràpida, sense barallar-te amb menús ni botons, només amb uns quants símbols col·locats als llocs correctes.

A GitHub el trobaràs per tot arreu: als arxius README.md dels repositoris, a les issues, a les pull requests, a les discussions i fins i tot al teu propi perfil. Reddit, per la seva banda, utilitza una variant anomenada Snoomark (Markdown amb sabor Reddit) que hereta bona part de la sintaxi de GitHub, amb algunes característiques pròpies i certes limitacions. A veure, pas a pas i amb molts exemples, com fer servir Markdown a GitHub ia Reddit de forma ràpida i sense deixar-te res important al tinter.

Què és Markdown i per què és tan útil a GitHub i Reddit

Markdown és un llenguatge de marcat lleuger ideat perquè el text sense format sigui fàcil de llegir i escriure, però que alhora es pugui transformar a HTML sense esforç. A la pràctica, això significa que pots escriure text normal i afegir alguns caràcters especials per aconseguir títols, llistes, taules, cites, codi formatat, enllaços o imatges.

A GitHub, la implementació que es fa servir és GitHub Flavored Markdown (GFM), que amplia la sintaxi clàssica amb taules, llistes de tasques, ressaltat de codi avançat, suport de colors, alertes i algunes etiquetes HTML permeses. Tot això es renderitza automàticament als fitxers .md i als camps de comentaris de la plataforma.

Reddit utilitza el seu propi processador anomenat Snoomark, una versió derivada de GFM. Comparteix bona part del comportament bàsic (negretes, cursives, encapçalats, llistes, cites, codi en línia o en bloc, enllaços…), però té particularitats importants : per exemple, el suport d'imatges és més limitat segons el context i afegeix elements propis com els spoilers.

La gràcia de tot això és que, amb una sola sintaxi, pots escriure textos que es veuen bé tant a GitHub com a Reddit, adaptant només alguns detalls on cada plataforma funciona de manera diferent. Aprendre les regles bàsiques et permet moure't amb soltesa en totes dues sense haver de reaprendre res de zero.

Encapçalats i estructura del contingut

Una de les primeres coses que utilitzaràs són les encapçalades , tant a GitHub com a Reddit. Serveixen per estructurar el text en seccions i subseccions.

A Markdown, una capçalera es crea anteposant d'un a sis símbols de coixinet al text: un per a un títol de nivell 1, dos per a nivell 2, i així fins al nivell 6. Per exemple, en un README.md de GitHub podries tenir alguna cosa com: # Títol principal , ## Secció , ### Subsección , etc.

GitHub, quan troba dos o més encapçalats en un fitxer, genera automàticament una taula de contingut accessible des de la icona de “Esquema” a la part superior del fitxer. Cada títol apareix com un enllaç que et porta directament a aquesta secció, cosa que ve genial en documents llargs.

A més, cada capçalera es converteix en una àncora interna a la qual podeu enllaçar amb un fragment d'URL basat en el text del títol. Per generar aquest fragment, GitHub aplica unes regles molt concretes: converteix les lletres a minúscules, reemplaça els espais per guions, elimina caràcters de puntuació i format (com a cursives), retalla espais sobrants i, si el resultat coincideix amb una altra capçalera prèvia, afegeix un sufix numèric (-1, -2, etc.).

Això permet fer coses com col·locar una secció ## Sample Section i després enllaçar-la des d'un altre punt del document amb un enllaç de l'estil (#sample-section) , o fins i tot enllaçar a seccions amb caràcters especials al títol, ja que GitHub genera el fragment seguint aquestes regles i ho fa accessible amb el mateix patró.

Èmfasi, text destacat i cites

Markdown et deixa ressaltar text usant diverses formes d' èmfasi : negreta, cursiva, text ratllat, subíndex, superíndex o subratllat. A GitHub, la taula d'estils típica quedaria més o menys així, encara que aquí ho resumim amb paraules diferents:

Per posar text en negreta , s'envolta amb dobles asteriscs o dobles guions baixos; per a la cursiva, es fan servir asteriscs o guions baixos simples; per ratllar alguna cosa, es recorre a la doble virgulilla (dues titlles de la ñ) a cada costat del fragment. També es poden combinar negreta i cursiva imbricades, fer servir tres asteriscs per aplicar totes dues a tot un tram de text, o recórrer a etiquetes HTML com _{i ^{per a subíndexs i superíndexs, i per a subratllats.}}

GitHub permet a més crear cites tipus blockquote anteposant el símbol més gran que al començament de la línia. El text esmentat es mostra amb una barra vertical a l'esquerra i en grisa, destacant-se de manera clara. Es poden tenir diverses línies dins del mateix bloc de cita, i fins i tot imbricar cites afegint més símbols a l'inici.

Una forma avançada de cita que només existeix a GitHub són les alertes o admonicions . Es basen en la mateixa sintaxi de blockquote, però la primera línia inclou un marcador especial per indicar el tipus d'alerta. Per exemple, podeu especificar per a informació útil, per a consells pràctics, per a dades clau, per a avisos urgents i per advertir de riscos o conseqüències negatives. GitHub mostra cada tipus amb un color i icona diferent, ajudant a ressaltar informació crítica a la documentació.

Reddit també suporta cites simples amb el mateix símbol >, encara que no compta amb el sistema d'alertes enriquides de GitHub. Tot i així, segueix sent una forma molt útil de respondre a algú citant part del seu missatge sense repetir-ho complet.

Ressaltat de codi, blocs i colors

Tant GitHub com Reddit permeten destacar fragments de codi dins del text usant cometes invertides. Per a codi en línia, es tanca la paraula o ordre amb una sola cometa invertida a cada costat. Això és ideal per ressaltar, per exemple, un git status dins una frase, deixant clar que és una ordre.

Quan vols un bloc de codi independent, Markdown utilitza tres cometes invertides: escrius una línia amb tres backticks, després el codi en línies separades i tanques amb tres backticks més. A GitHub, si a més indiqueu el llenguatge just després de les primeres cometes invertides, s'aplica ressaltat de sintaxi amb colors i format específic per a aquest llenguatge.

GitHub ofereix també una funció específica per ressaltar valors de color dins de cometes invertides. Si escriviu un color en format hexadecimal, RGB o HSL entre backticks, la plataforma inclou un petit indicador de color al costat del text. Per exemple, si el fons en mode clar té el color #ffffff i en mode fosc #000000, destacar aquests codis permet veure ràpidament quin és quin.

Pel que fa a la visualització del codi i les taules, GitHub et deixa activar una font monoespaiada fixa a tots els camps de comentaris perquè treballar amb text tècnic sigui més còmode. Si edites molts fragments de codi des del navegador o en editors com Visual Studio Code , activar aquesta opció fa que l'alineació i la lectura siguin molt més coherents.

Reddit també suporta blocs de codi amb backticks, tant en línia com en bloc, encara que el seu ús se centra més en petits fragments o pseudocodi que en documentació llarga com la d'un repositori.

Enllaços, àncores i navegació interna

Crear enllaços a Markdown és molt senzill: es tanca el text que es mostrarà a l'usuari entre claudàtors i la URL entre parèntesis. Això funciona tant a GitHub com a Reddit, i es pot complementar amb dreceres de teclat a GitHub (per exemple, utilitzar combinacions de tecles per convertir ràpidament text seleccionat en un enllaç).

GitHub afegeix algunes funcionalitats extra relacionades amb la navegació. Per una banda, permet enllaçar directament a encapçalats usant les regles de generació de fragments comentades abans. De l'altra, suporta enllaços relatius dins del mateix repositori, cosa clau en documentació tècnica.

Un enllaç relatiu és aquell que es calcula prenent com a referència el fitxer actual. Per exemple, si el teu README està a l'arrel del projecte i vols enllaçar un fitxer docs/CONTRIBUTING.md, només cal escriure un enllaç la ruta del qual sigui docs/CONTRIBUTING.md. GitHub s'encarrega de traduir aquest enllaç relatiu de forma correcta en qualsevol branca on et trobis, cosa que evita que es trenquin en canviar de branca o clonar el repositori.

La recomanació és utilitzar sempre rutes relatives per navegar entre fitxers del mateix dipòsit, perquè els enllaços absoluts poden deixar de funcionar en clons o forks. GitHub permet utilitzar operadors estàndard com ./ o ../ i rutes que comencin per / relatives a l'arrel del projecte.

Si voleu crear punts d'ancoratge personalitzats dins d'un document més enllà de les capçaleres, podeu recórrer a etiquetes HTML amb atribut name. Això permet situar un punt de destinació enmig d'un paràgraf o al costat d'un text que no té títol propi, i enllaçar-lo usant la mateixa sintaxi que per a les capçaleres generades automàticament.

Imatges a GitHub: Markdown, HTML i rutes relatives

A GitHub, les imatges s'insereixen generalment amb la mateixa sintaxi que els enllaços, però precedida per un signe d'exclamació. Entre claudàtors s'especifica el text alternatiu (alt) i entre parèntesis la URL o la ruta de la imatge. Aquest text alternatiu és important per a l' accessibilitat , ja que és el que llegiran els lectors de pantalla i el que es mostrarà si la imatge no carrega.

Les imatges poden procedir tant de fitxers del mateix repositori com d'URLs externes. GitHub permet múltiples patrons de rutes relatives per carregar imatges des de diferents branques, des d'altres repositoris o fins i tot des de issues i comentaris, utilitzant sufixos com a ?raw=true per forçar la descàrrega directa del fitxer quan és necessari.

A més de la sintaxi estàndard de Markdown, el GitHub suporta l'ús de l'element HTML <picture>. Aquest element és especialment útil per carregar imatges responsives que canvien segons les preferències del tema de l'usuari (clar o fosc). Mitjançant la mitjana query prefers-color-scheme podeu definir diferents fonts d'imatge per a cada mode, i una imatge per defecte per a navegadors que no suporten aquesta característica.

El patró típic consisteix a incloure dins de diversos elements amb els seus atributs media i srcset, i al final un amb l'atribut alt i un URL genèric. Així s'aconsegueix que qui utilitzi mode fosc vegi una imatge adaptada, i qui estigui en mode clar en rebi una altra de diferent, sense haver de duplicar contingut al README.

GitHub també admet comentaris HTML als fitxers Markdown, cosa que et permet afegir recordatoris invisibles al lector, per exemple per recordar que has d'actualitzar una secció d'imatges o afegir nous exemples més endavant.

Taules, seccions plegables i separació de contingut

Una de les millores més útils de GitHub Flavored Markdown és el suport de taules . Podeu organitzar dades en files i columnes usant barres verticals per separar cel·les i una fila de guions per marcar la capçalera. També és possible alinear columnes a la dreta, a l'esquerra o al centre, utilitzant dos punts a la fila de separació.

Les taules són molt útils per presentar llistes de llenguatges de programació, frameworks usats, tasques planificades, comparatives de característiques o qualsevol altra informació que es beneficiï duna estructura matricial. GitHub renderitza aquestes taules amb un estil net i llegible.

Per mantenir ordenat un README llarg, podeu utilitzar l'etiqueta HTML <details> per crear seccions plegables. Aquestes seccions mostren un resum dins de l'etiqueta <summary> i permeten que l'usuari expandeixi o contregui contingut addicional segons calgui. És habitual tancar taules o blocs d'informació secundària dins de <details> per no saturar a primera vista.

Si voleu que la secció aparegui desplegada per defecte, només cal afegir l'atribut open a . Aquesta tècnica és molt pràctica per agrupar rànquings, llistes llargues o continguts que no són essencials per a una primera lectura però que cal tenir accessibles.

Una altra eina senzilla per organitzar la informació és la regla horitzontal. Es genera escrivint tres guions o més en una línia i serveix per traçar una línia divisòria entre seccions, permetent separar clarament, per exemple, una part descriptiva d'una secció de referències o de notes addicionals.

Aquestes regles es poden combinar amb cites al final del document per ressaltar frases inspiradores, recordatoris o missatges clau. Un exemple típic seria col·locar una cita motivacional al final del teu README de perfil, formatat amb un blockquote després d'una línia separadora.

Comentaris ocults i control del format

GitHub us permet introduir comentaris HTML dins del Markdown usant la sintaxi <!– comentari –>. Tot el que col·loquis dins d'aquest comentari no es mostrarà en el contingut renderitzat, però sí que serà visible al codi font, per la qual cosa és ideal per a notes internes o tasques pendents.

Per exemple, a un README de perfil pots afegir un comentari que digui alguna cosa com que has d'ampliar la secció “About me” més endavant o que necessites revisar una taula de tecnologies obsoletes, sense que ningú que visiti el perfil el vegi directament.

Una altra funció útil és escapar caràcters que normalment s'interpretarien com Markdown. Si necessites mostrar literalment asteriscs, coixinets o altres símbols sense que es transformin en format, només cal anteposar una barra invertida a cadascun. Això permet, per exemple, escriure expressions que incloguin símbols de llista sense convertir-les en llistes reals.

Quan veieu un fitxer de marcatge a GitHub, teniu l'opció d'alternar entre la vista renderitzada i el codi font amb un botó a la part superior (o obrir-lo en editors com Brackets ). Desactivar la interpretació de Markdown et deixa accedir a funcions típiques de la vista de codi com enllaçar línies concretes , cosa molt útil quan vols assenyalar una part exacta d'un README o de qualsevol fitxer .md.

Finalment, recorda que GitHub processa de manera diferent els salts de línia en comentaris (issues, PRs, etc.) i en fitxers .md. En comentaris, els salts de línia es respecten directament, mentre que en fitxers Markdown necessites afegir dos espais al final de la línia, una barra invertida o un per forçar el salt dins del mateix paràgraf.

Llistes, llistes imbricades i llistes de tasques

Les llistes són un dels elements més usats a Markdown, tant a GitHub com a Reddit. Podeu crear llistes no ordenades anteposant un guió, un asterisc o un signe més a cada element de la llista. Totes aquestes marques es renderitzen de forma similar com a vinyetes.

Per generar llistes ordenades , cada línia es numera amb un número seguit d'un punt i un espai. Encara que l'ordre dels números no ha de ser perfecte (GitHub sol recalcular-ho), és bona idea mantenir una numeració coherent perquè el codi font sigui llegible.

Les llistes imbricades es creen simplement afegint sagnia als elements inferiors. En editors monoespaiats com Sublime Text , només cal alinear visualment les marques de llista imbricada sota el primer caràcter del text de l'element superior. En contextos com l'editor de comentaris de GitHub, on la font no és monoespaiada, convé comptar quants caràcters hi ha abans del text i fer servir aquest nombre d'espais per a la sagnia.

També podeu construir diversos nivells de nidificació, sempre que mantingueu la coherència en el nombre d'espais. Per a llistes molt complexes, aquest sistema requereix una mica de pràctica, però un cop interioritzat és molt ràpid d'aplicar.

GitHub ofereix a més les llistes de tasques , molt útils en issues, pull requests i documentació. Es creen anteposant un guió, un espai i una parella de claudàtors amb espai en blanc o amb una x dins: per a tasques pendents i per a tasques completades. Aquestes llistes es renderitzen amb caselles de selecció que es poden marcar o desmarcar des de la interfície.

Si el text d'un element de llista de tasques comença per un parèntesi, cal escapar-lo amb una barra invertida per evitar confusions al parser. És un petit detall, però important quan redactes descripcions que comencen per alguna cosa com ara (Opcional) o similar.

Mencions, referències i emojis a GitHub

Un dels avantatges d'escriure a Markdown a GitHub és poder fer servir mencions directes a usuaris i equips de la plataforma. Simplement escrius @ seguit del nom dusuari o de lequip, i GitHub dispara una notificació a aquest compte, atraient la seva atenció a la conversa.

En escriure el símbol @, GitHub desplega una llista d'usuaris i equips relacionats amb el repositori o el fil, i pots anar filtrant aquesta llista a mesura que tecleges. Amb les fletxes i la tecla Enter o Tab acceptes el suggeriment. En el cas dels equips, s'usa la forma @organització/nom-del-equip i tots els seus membres queden subscrits al fil.

A més de mencions, GitHub facilita referenciar issues i pull requests només escriure # seguit d'un número o part del títol. Es mostra una llista de resultats suggerits que podeu completar de la mateixa manera que amb les mencions. Això agilitza moltíssim la navegació entre converses relacionades.

Si al vostre repositori s'han configurat referències autovinculades personalitzades, també és possible que determinades notacions externes (com identificadors de tiquets de JIRA o Zendesk) es transformin automàticament en enllaços curts. Aquesta configuració requereix permisos administratius, però un cop activada permet creuar informació entre sistemes amb un esforç mínim.

Finalment, GitHub admet emojis mitjançant codi: escrivint dos punts, seguit del nom de l'emoji i acabant de nou amb dos punts. En començar a escriure apareix una llista de suggeriments que podeu acceptar amb Tab o Enter. Incorporar emojis als teus comentaris ajuda a donar-los un to més humà, sempre que no n'abusis en documentació formal.

Notes al peu i contingut avançat

GitHub suporta també notes al peu usant una sintaxi basada en claudàtors i un identificador amb un caràcter d'intercalat. Al punt on vols la referència, insereixes alguna cosa com , i al final del document defineixes el text d'aquesta nota amb la mateixa etiqueta, seguida de dos punts i el contingut.

Les notes al peu poden tenir diverses línies, i per forçar salts dins la nota s'utilitzen espais dobles al final de la línia, igual que al cos principal del Markdown. En renderitzar, GitHub mostra un superíndex al text i una llista de notes al peu al final, amb enllaços d'anada i tornada per moure's entre referència i nota.

Un altre element avançat que ofereix GitHub són les alertes ja comentades (NOTE, TIP, IMPORTANT, WARNING i CAUTION). És recomanable utilitzar-les només quan sigui realment necessari, i no encadenar massa una darrere l'altra per no saturar el lector. No es poden niar dins altres elements complexos, així que convé planificar bé on es col·loquen.

Finalment, podeu demanar-li a GitHub que oculti temporalment seccions de Markdown renderitzat embolicant-les en comentaris HTML, o que ignori el processament de certs caràcters amb barres invertides. Això és especialment útil quan estàs documentant la pròpia sintaxi de Markdown i necessites mostrar exemples tal qual, sense que s'interpretin.

Markdown a Reddit: Snoomark i mode d'edició

Reddit és una plataforma de discussió on gairebé qualsevol tema hi té cabuda, organitzat en subfòrums anomenats subreddits. A nivell de format, ofereix dos editors: un de text enriquit més visual i un altre de text pla basat en Markdown. Si vols anar ràpid i tenir un control fi sobre el resultat, t'interessa fer servir l'opció de Markdown.

Per defecte, Reddit sol activar l'editor de text enriquit, així que per canviar al mode de marcatge heu de fer clic a l'opció Markdown mode dins del quadre d'escriptura d'un post o comentari. A partir d'aquí, podeu utilitzar la sintaxi Snoomark de forma directa.

Si preferiu que sempre es carregui l'editor de Markdown, heu d'anar a la configuració d'usuari, entrar a la secció de configuració del feed (Feed Settings) i activar l'opció Default to markdown . D'aquesta manera, cada cop que comenceu a escriure un post o un comentari s'obrirà l'editor de Markdown sense haver de canviar-lo a mà.

Reddit suporta la majoria d'elements bàsics i avançats de Markdown: encapçalats, negretes i cursives, llistes, cites, blocs de codi, enllaços i alguns extres propis com els spoilers. Tot i això, té mancances rellevants respecte a GitHub, especialment en el maneig d'imatges , que depèn força del context i del tipus d'editor.

Sintaxi suportada per Reddit i spoilers

La variant Snoomark que utilitza Reddit inclou molts elements en comú amb GitHub, així que si ja domines Markdown en repositoris, traslladar aquest coneixement a l'entorn de Reddit és força directe. Pots utilitzar capçaleres per estructurar publicacions llargues, llistes numerades o amb vinyetes, cites per respondre altres usuaris i blocs de codi quan vulguis mostrar ordres o fragments tècnics.

Una de les diferències notables és la manera com Reddit gestiona les imatges . Encara que en molts casos les imatges es pugen mitjançant la interfície gràfica i no directament amb sintaxi Markdown, el motor que processa el contingut de text segueix sent Snoomark, de manera que el format que envolta aquestes imatges sí que es basa en Markdown.

Reddit, per altra banda, afegeix elements addicionals que no formen part de l'especificació estàndard, com ara els spoilers. Aquests permeten ocultar text darrere d'una capa que l'usuari pot revelar amb un clic. Tècnicament, quan Reddit processa un spoiler, ho transforma a una combinació d'HTML, classes CSS i JavaScript propis de la plataforma.

La representació HTML resultant d'un spoiler inclou manejadors que controlen quan mostrar o ocultar el contingut, i encara que a nivell teòric es podria escriure una cosa semblant amb HTML simple, a Reddit depèn de la seva implementació interna. L'important per a tu com a usuari és que, en escriure, només necessites fer servir la sintaxi específica de spoiler que ofereixi l'editor, i Snoomark s'encarrega de traduir-lo a l'estructura adequada.

En definitiva, Snoomark hereta molts comportaments de GitHub Flavored Markdown, però orientats a les necessitats duna comunitat de discussió més que a la documentació de projectes. Tot i així, el nucli és el mateix: text pla amb símbols senzills que es converteixen en un contingut estructurat i llegible.

Dominar la sintaxi de Markdown a GitHub i Reddit fa que escriure documentació tècnica, obrir issues ben explicades, deixar comentaris clars a pull requests i participar en debats de Reddit sigui molt més àgil. Amb unes poques regles clau —encapçalades, èmfasi, llistes, cites, blocs de codi, enllaços, imatges i trucs específics com taules, detalls plegables, alertes, notes al peu o spoilers— passes de deixar missatges plans a crear continguts nets, escanejables i professionals sense tocar un sol botó del ratolí.