Cum să folosești rapid Markdown pe GitHub și Reddit

Informatec Digital » Recursos » Cum să folosești rapid Markdown pe GitHub și Reddit

Dacă scrii în mod regulat pe GitHub sau petreci mult timp pe Reddit, stăpânirea Reduceri Este unul dintre acele lucruri care îți economisesc ore întregi și îți fac viața mai ușoară. Este un limbaj de marcare foarte ușor, care îți permite să formatezi rapid text simplu, fără a te chinui cu meniurile sau butoanele, doar cu câteva simboluri plasate în locurile potrivite.

Pe GitHub îl veți găsi peste tot: în fișiere README.md din repozitorii, probleme, cereri de extragere, discuții și chiar propriul profil. Reddit, la rândul său, folosește o variantă numită Snoomark (Markdown în stil Reddit) care moștenește o mare parte din sintaxa GitHub, cu unele caracteristici unice și anumite limitări. Să vedem, pas cu pas și cu multe exemple, Cum să folosești rapid Markdown pe GitHub și Reddit și fără a omite nimic important.

Ce este Markdown și de ce este atât de util pe GitHub și Reddit?

Markdown este o limbaj de marcare ușor Conceput pentru a facilita citirea și scrierea textului simplu, permițând în același timp conversia fără efort în HTML. În practică, aceasta înseamnă că puteți scrie text obișnuit și adăuga caractere speciale pentru a crea titluri, liste, tabele, citate, cod formatat, linkuri sau imagini.

La GitHub, implementarea utilizată este GitHub Flavored Markdown (GFM), care extinde sintaxa clasică cu tabele, liste de activități, evidențiere avansată a codului, suport pentru culori, alerte și unele etichete HTML permise. Toate acestea sunt redate automat în fișierele .md și în câmpurile de comentarii ale platformei.

Reddit folosește propriul procesor numit Snoomark, un derivat al GFM. Acesta are în comun o mare parte din comportamentul de bază (aldin, italic, titluri, liste, citate, cod în linie sau bloc, linkuri etc.), dar are caracteristici importanteDe exemplu, suportul pentru imagini este mai limitat în funcție de context și adaugă propriile elemente, cum ar fi spoilere.

Frumusețea tuturor acestor lucruri constă în faptul că, cu o singură sintaxă, poți scrie texte care arată bine atât pe GitHub, cât și pe Reddit, adaptând doar câteva detalii acolo unde fiecare platformă funcționează diferit. Învață regulile de bază Îți permite să te miști liber în ambele, fără a fi nevoie să înveți nimic de la zero.

Titluri și structura conținutului

Unul dintre primele lucruri pe care le veți folosi sunt anteteAtât pe GitHub, cât și pe Reddit, acestea sunt folosite pentru a structura textul în secțiuni și subsecțiuni.

În Markdown, un titlu este creat prin plasarea unuia până la șase simboluri hash înaintea textului: unul pentru un titlu de nivel 1, două pentru nivelul 2 și așa mai departe până la nivelul 6. De exemplu, într-un fișier GitHub README.md ați putea avea ceva de genul: # Titlul principal, ## Secțiune, ### Subsecțiune, Etc

Când GitHub găsește două sau mai multe anteturi într-un fișier, generează automat un cuprins Accesibil prin pictograma „Schiță” din partea de sus a fișierului. Fiecare titlu apare ca un link care vă duce direct la secțiunea respectivă, ceea ce este excelent pentru documentele lungi.

În plus, fiecare titlu devine o ancoră internă la care puteți face legătura printr-un fragment de URL bazat pe textul titlului. Pentru a genera acel fragment, GitHub aplică reguli foarte specifice: convertește literele în minuscule, înlocuiește spațiile cu cratime, elimină semnele de punctuație și caracterele de formatare (cum ar fi italicele), elimină spațiile în exces și, dacă rezultatul se potrivește cu un alt titlu anterior, adăugați un sufix numeric (-1, -2 etc.) pentru a-l face unic.

Acest lucru vă permite să faceți lucruri precum plasarea unei secțiuni ## Secțiune exemplu și apoi creați un link către acesta dintr-un alt punct din document cu un link de genul acesta: (#secțiune-exemplu)sau chiar link-uri către secțiuni cu caractere speciale în titlu, deoarece GitHub generează fragmentul de cod urmând acele reguli și îl face accesibil cu același model.

Accentuare, text evidențiat și citate

Markdown vă permite să evidențiați textul folosind diverse metode accentBold, italic, tăiat cu o linie, subscript, expositor sau subliniat. Pe GitHub, tabelul de stil tipic ar arăta cam așa, deși l-am rezumat aici cu cuvinte diferite:

Pentru a pune text caractere aldineTextul îngroșat este inclus între asteriscuri duble sau sublinieri duble; pentru italic, se folosesc asteriscuri simple sau sublinieri; pentru a tăia ceva cu o linie, se plasează o tildă dublă (două tilde) pe fiecare parte a textului. De asemenea, se pot combina caracterele îngroșate și italice imbricate, se pot folosi trei asteriscuri pentru a aplica ambele unei secțiuni întregi de text sau se pot folosi etichete HTML precum <br>. _{y ^{pentru indici și exponenți și pentru subliniere.}}

GitHub vă permite, de asemenea, să creați citate în stil blockquote Prin plasarea simbolului mai mare decât (>) la începutul rândului, textul citat este afișat cu o bară verticală în stânga și gri, ceea ce îl face să iasă în evidență. Mai multe rânduri pot fi incluse în același bloc de citate, iar citatele pot fi chiar imbricate prin adăugarea mai multor simboluri > la început.

O formă avansată de citare care există doar pe GitHub este alerte sau avertismenteAcestea se bazează pe aceeași sintaxă pentru citate bloc, dar prima linie include un marker special pentru a indica tipul de alertă. De exemplu, puteți specifica `<alert>` pentru informații utile, `<helpful tips>` pentru sfaturi practice, `<key data>` pentru date cheie, `<urgent notices>` pentru avertismente urgente și `<alert>` pentru avertismente privind riscuri sau consecințe negative. GitHub afișează fiecare tip cu o culoare și o pictogramă diferite, ajutând la evidențierea informațiilor critice din documentație.

Reddit acceptă și citate simple cu același simbol >, deși îi lipsește sistemul bogat de alerte al lui GitHub. Chiar și așa, rămâne o modalitate foarte utilă de a a răspunde cuiva citând o parte din mesajul său fără a o repeta complet.

Evidențierea codului, blocuri și culori

Atât GitHub, cât și Reddit vă permit să evidențiați fragmente de cod în text folosind acronimul. Pentru codul inline, încadrați cuvântul sau comanda cu un singur acronim pe fiecare parte. Acest lucru este ideal pentru evidențierea, de exemplu, a unui starea git în cadrul unei propoziții, precizând clar că este o comandă.

Când dorești un bloc de cod independent, Markdown folosește trei acronime: scrii o linie cu trei acronime, apoi codul pe linii separate și închei cu alte trei acronime. Pe GitHub, dacă specifici și limba imediat după primul acronime, se aplică... evidențierea sintaxei cu culori și format specifice limbii respective.

GitHub oferă și o funcție specifică pentru evidențierea valorile culorii în cadrul apiciilor inversate. Dacă tastați o culoare în format hexazecimal, RGB sau HSL între apicii inversate, platforma include un mic indicator de culoare lângă text. De exemplu, dacă culoarea de fundal în modul luminos este #ffffff și în modul întunecat este #000000, evidențierea acestor coduri vă permite să vedeți rapid care este care.

În ceea ce privește vizualizarea codului și a tabelelor, GitHub vă permite să activați un font monospațial fix în toate câmpurile de comentarii pentru a face lucrul cu text tehnic mai confortabil. Dacă editați multe fragmente de cod în browser sau în editori precum Codul Visual StudioActivarea acestei opțiuni facilitează alinierea și citirea. mult mai coerent.

Reddit acceptă, de asemenea, blocuri de cod cu backticks, atât inline, cât și block, deși utilizarea lor acolo se concentrează mai mult pe fragmente mici sau pseudocod decât pe documentație lungă, cum ar fi cea a unui repository.

Linkuri, ancore și navigare internă

Crearea de linkuri în Markdown este foarte simplă: textul care va fi afișat utilizatorului este inclus între paranteze pătrate, iar adresa URL este inclusă între paranteze. Acest lucru funcționează atât pe GitHub, cât și pe Reddit și poate fi îmbunătățit cu ajutorul comenzilor rapide de la tastatură pe GitHub (de exemplu, utilizarea combinațiilor de taste pentru a converti rapid textul selectat într-un link).

GitHub adaugă câteva funcții suplimentare legate de navigare. În primul rând, permite legătură directă către titluri utilizând regulile de generare a fragmentelor discutate anterior. În plus, acceptă legături relative în cadrul depozitului, ceea ce este crucial în documentația tehnică.

O legătură relativă este una calculată folosind fișierul curent ca referință. De exemplu, dacă fișierul README se află în rădăcina proiectului și doriți să creați o legătură către un fișier docs/CONTRIBUTING.md, pur și simplu scrieți o legătură cu calea docs/CONTRIBUTING.md. GitHub se ocupă de traducerea corectă a acestei legături relative în orice ramură în care vă aflați, împiedicând întreruperea acesteia la schimbarea ramurilor sau la clonarea depozitului.

Recomandarea este să folosiți întotdeauna căi relative Pentru a naviga între fișiere din același repository, deoarece linkurile absolute pot înceta să funcționeze în clone sau fork-uri, GitHub permite utilizarea operatorilor standard, cum ar fi ./ sau ../, și a căilor care încep cu / relative la rădăcina proiectului.

Dacă doriți să creați puncte de ancorare personalizate în cadrul unui document, dincolo de titluri, puteți utiliza etichete HTML cu atributul `name`. Aceasta vă permite să plasați un punct țintă în mijlocul unui paragraf sau lângă un text care nu are propriul titlu și să creați un link către acesta folosind aceeași sintaxă ca în cazul titlurilor generate automat.

Imagini pe GitHub: Markdown, HTML și căi relative

Pe GitHub, imaginile sunt în general încorporate folosind aceeași sintaxă ca și linkurile, dar precedate de un semn de exclamare. Textul alternativ (alt) este specificat între paranteze pătrate, iar adresa URL sau calea către imagine este plasată între paranteze. Acest text alternativ este important pentru accesibilitatepentru că asta vor citi cititoarele de ecran și asta va fi afișat dacă imaginea nu se încarcă.

Imaginile pot proveni din fișiere din interiorul depozitului sau din adrese URL externe. GitHub permite mai multe modele de căi relative pentru încărcarea imaginilor din diferite ramuri, alte depozite sau chiar din probleme și comentarii, folosind sufixe precum ?brut=adevărat pentru a forța descărcarea directă a fișierului atunci când este necesar.

Pe lângă sintaxa standard Markdown, GitHub acceptă utilizarea elementului HTML Acest articol este util în special pentru încărcare imagini responsive Acestea se schimbă în funcție de preferințele utilizatorului privind tema (luminoasă sau întunecată). Folosind interogarea media `prefers-color-scheme`, puteți defini surse de imagine diferite pentru fiecare mod și o imagine implicită pentru browserele care nu acceptă această funcție.

Modelul tipic implică includerea în cadrul mai multe elemente cu atributele sale media și srcset și, în final, un Folosind atributul alt și o adresă URL generică, utilizatorii aflați în modul întunecat văd o imagine adaptată, în timp ce cei aflați în modul luminos primesc una diferită, fără a fi nevoie să duplice conținutul din fișierul README.

GitHub acceptă și comentarii HTML în fișierele Markdown, permițându-vă să adăugați mementouri invizibile pentru cititor, de exemplu pentru a-i reaminti să actualizeze o secțiune de imagine sau să adauge exemple noi ulterior.

Tabele, secțiuni pliabile și separarea conținutului

Una dintre cele mai utile îmbunătățiri din GitHub Flavored Markdown este suportul pentru tragePuteți organiza datele în rânduri și coloane folosind bare verticale pentru a separa celulele și o linie punctată pentru a marca antetul. De asemenea, puteți alinia coloanele la dreapta, la stânga sau la centru folosind două puncte în rândul separator.

Tabelele sunt foarte utile pentru prezentarea listelor de limbaje de programare, framework-uri utilizate, sarcini planificate, comparații de caracteristici sau orice alte informații care beneficiază de o structură matriceală. GitHub redă aceste tabele într-un stil curat și ușor de citit.

Pentru a păstra organizat un fișier README lung, puteți utiliza eticheta HTML pentru a crea secțiuni restrângibile. Aceste secțiuni afișează un rezumat în cadrul etichetei și permite utilizatorului să extindă sau să contracteze continut suplimentar după cum este necesar. Este obișnuit să se includă tabele sau blocuri de informații secundare în pentru a evita suprasolicitarea ochiului.

Dacă doriți ca secțiunea să apară extinsă în mod implicit, pur și simplu adăugați atributul open la Această tehnică este foarte practică pentru gruparea clasamentelor, a listelor lungi sau a conținutului care nu este esențial pentru o primă lectură, dar este convenabil de avut la îndemână.

Un alt instrument simplu pentru organizarea informațiilor este regula orizontală. Aceasta se creează prin scrierea a trei sau mai multe liniuțe pe o linie și servește la trasarea unei linii de demarcație între secțiuni, permițând separarea clară, de exemplu, a unei secțiuni descriptive de o secțiune de referințe sau note suplimentare.

Aceste reguli pot fi combinate cu citate de la sfârșitul documentului pentru a evidenția fraze inspiraționale, mementouri sau mesaje cheie. Un exemplu tipic ar fi plasarea unui citat motivațional la sfârșitul fișierului README din profilul dvs., formatat cu un citat bloc după o linie de separare.

Comentarii ascunse și control al formatului

GitHub vă permite să prezentați Comentarii HTML în Markdown folosind sintaxa Orice ai pune în acel comentariu nu va fi afișat în conținutul randat, dar va fi vizibil în codul sursă, deci este ideal pentru note interne sau sarcini de rezolvat.

De exemplu, într-un fișier README de profil puteți adăuga un comentariu care spune ceva de genul că trebuie să extindeți secțiunea „Despre mine” mai târziu sau că trebuie să revizuiți un tabel cu tehnologii învechite, fără ca cineva care vizitează profilul să îl vadă direct.

O altă funcție utilă este cea de a personaje de evadare ceea ce ar fi interpretat în mod normal ca Markdown. Dacă trebuie să afișați asteriscuri, simboluri hash sau alte simboluri literal, fără a fi formatate, pur și simplu precedați fiecare dintre ele cu o bară oblică inversată. Acest lucru vă permite, de exemplu, să scrieți expresii care includ simboluri de listă fără a le converti în liste propriu-zise.

Când vizualizați un fișier de markup pe GitHub, aveți opțiunea de a comuta între vizualizarea randată și codul sursă cu un buton din partea de sus (sau de a-l deschide în editori precum ConsoleDezactivarea interpretării Markdown vă permite să accesați funcțiile tipice de vizualizare a codului, cum ar fi legătură de linii specificeAcest lucru este foarte util atunci când vrei să indice o parte exactă a unui fișier README sau a oricărui fișier .md.

În cele din urmă, rețineți că GitHub gestionează sfârșiturile de linie diferit în comentarii (probleme, PR-uri etc.) și în fișierele .md. În comentarii, sfârșiturile de linie sunt respectate direct, în timp ce în fișierele Markdown trebuie să adăugați două spații la sfârșitul liniei, o bară oblică inversată sau un punct. pentru a forța saltul în cadrul aceluiași paragraf.

Liste, liste imbricate și liste de activități

Listele sunt printre cele mai utilizate elemente în Markdown, atât pe GitHub, cât și pe Reddit. Puteți crea liste neordonat prin plasarea unei cratime, a unui asterisc sau a unui semn plus înaintea fiecărui element din listă. Toate aceste semne sunt redate similar ca puncte.

Pentru a genera liste ordonatFiecare linie este numerotată cu un număr urmat de un punct și un spațiu. Deși ordinea numerelor nu trebuie să fie perfectă (GitHub o recalculează de obicei), este o idee bună să mențineți o numerotare consistentă pentru a face codul sursă lizibil.

Listele imbricate sunt create pur și simplu prin adăugarea de indentare la elementele de sub ele. În editorii monospațiați, cum ar fi Textul SublimePur și simplu aliniați vizual marcajele listei imbricate sub primul caracter al textului din elementul părinte. În contexte precum editorul de comentarii GitHub, unde fontul nu este monospațiat, numărați numărul de caractere dinaintea textului și folosiți acel număr de spații pentru indentare.

De asemenea, puteți construi mai multe niveluri de imbricare, atâta timp cât mențineți consecvența în ceea ce privește numărul de spații. Pentru liste foarte complexe, acest sistem necesită puțină practică, dar odată ce vă obișnuiți cu el, este foarte rapid de aplicat.

GitHub oferă, de asemenea, liste de sarciniAcestea sunt foarte utile pentru probleme, cereri de extragere (pull requests) și documentație. Sunt create prin plasarea unui spațiu sau a unui „x” înaintea unei cratime, a unui spațiu și a unei perechi de paranteze pătrate: pentru sarcinile în așteptare și pentru sarcinile finalizate. Aceste liste sunt redate cu casete de selectare care pot fi bifate sau debifate din interfață.

Dacă textul unui element din lista de activități începe cu paranteze, acesta trebuie să fie marcat cu o bară oblică inversată pentru a evita confuzia în parser. Este un detaliu mic, dar important atunci când scrieți descrieri care încep cu ceva de genul „(Opțional)” sau ceva similar.

Mențiuni, referințe și emoji-uri pe GitHub

Unul dintre avantajele scrierii în Markdown pe GitHub este posibilitatea de a utiliza menționează Mesaje directe către utilizatori și echipe de pe platformă. Pur și simplu tastați @ urmat de numele de utilizator sau de numele echipei, iar GitHub va trimite o notificare către contul respectiv, atrăgându-i atenția asupra conversației.

Când tastezi simbolul @, GitHub afișează o listă de utilizatori și echipe asociate cu repozitoriul sau firul de discuție, iar tu poți filtra această listă pe măsură ce tastezi. Folosește tastele săgeată și apasă Enter sau Tab pentru a accepta sugestiile. Pentru echipe, folosește formatul @organizație/nume-echipă, iar toți membrii echipei vor fi abonați la firul de discuție.

Pe lângă mențiuni, GitHub facilitează probleme de referință și cereri de extragere Pur și simplu tastați # urmat de un număr sau o parte din titlu. Va apărea o listă de rezultate sugerate, pe care o puteți completa în același mod ca și în cazul mențiunilor. Acest lucru accelerează considerabil navigarea între conversațiile corelate.

Dacă depozitul dvs. are configurate referințe personalizate cu link-uri automate, anumite notații externe (cum ar fi ID-urile de tichete JIRA sau Zendesk) pot fi, de asemenea, convertite automat în link-uri scurte. Această setare necesită privilegii administrative, dar odată activată, permite partajarea datelor între sisteme cu efort minim.

În cele din urmă, GitHub acceptă emoji-uri prin cod: tastați două puncte, urmate de numele emoji-ului și terminați cu încă două puncte. Pe măsură ce începeți să tastați, apare o listă de sugestii, pe care le puteți accepta apăsând Tab sau Enter. Incorporarea emoji-urilor în comentarii vă ajută să le dați o notă mai umană, atâta timp cât nu le utilizați excesiv în documentația formală.

Note de subsol și conținut avansat

GitHub acceptă, de asemenea, Note de subsol Folosind o sintaxă bazată pe paranteze și un identificator cu un caracter intercalat. În punctul în care doriți referința, inserați ceva de genul , iar la sfârșitul documentului definiți textul acelei note cu aceeași etichetă, urmat de două puncte și conținut.

Notele de subsol se pot întinde pe mai multe rânduri, iar pentru a forța întreruperi de rând în cadrul unei note de subsol, se folosesc spații duble la sfârșitul rândului, la fel ca în corpul principal al Markdown-ului. La randare, GitHub afișează un exponent pe text și o listă de note de subsol la sfârșit, cu backlink-uri pentru navigarea între referințe și note de subsol.

O altă funcționalitate avansată oferită de GitHub este... alerte Acestea au fost deja discutate (NOTĂ, SFAT, IMPORTANT, AVERTISMENT și ATENȚIE). Este recomandabil să le folosiți doar atunci când este cu adevărat necesar și să evitați înșirarea prea multor elemente pentru a nu copleși cititorul. Nu pot fi imbricate în alte elemente complexe, așa că este esențială o planificare atentă a plasării lor.

În cele din urmă, puteți solicita GitHub să ascundă temporar secțiuni din Markdown-ul randat, încadrându-le în comentarii HTML sau să ignore procesarea anumitor caractere cu backslash-uri. Acest lucru este util mai ales atunci când documentați. Sintaxa proprie a lui Markdown Și trebuie să arăți exemplele așa cum sunt, fără interpretări.

Markdown pe Reddit: Snoomark și modul de editare

Reddit este o platformă de discuții unde aproape orice subiect este binevenit, organizat în subreddituri. În ceea ce privește formatarea, oferă două editoare: unul pentru text îmbogățit, care este mai vizual, și altul pentru text simplu, bazat pe Markdown. Dacă vrei să lucrezi rapid și să ai un control fin asupra rezultatului, vei dori să folosești opțiunea Markdown.

În mod implicit, Reddit activează de obicei editorul de text îmbogățit, așa că pentru a comuta la modul de marcare trebuie să faceți clic pe opțiunea Mod Markdown în caseta de text a unei postări sau comentarii. De acolo, puteți utiliza direct sintaxa Snoomark.

Dacă preferați ca editorul Markdown să se încarce întotdeauna, trebuie să accesați setările utilizatorului, să accesați secțiunea Setări feed și să activați opțiunea Implicit la reducereÎn acest fel, de fiecare dată când începi să scrii o postare sau un comentariu, editorul Markdown se va deschide automat fără a fi nevoie să îl modifici manual.

Reddit acceptă majoritatea funcțiilor Markdown de bază și avansate: titluri, caractere aldine și italice, liste, citate, blocuri de cod, linkuri și câteva extra-uri proprii, cum ar fi spoilere. Cu toate acestea, are deficiențe semnificative în comparație cu GitHub, în ​​special în ceea ce privește... gestionarea imaginilorceea ce depinde destul de mult de context și de tipul de editor.

Sintaxă acceptată de Reddit și spoilere

Varianta Snoomark utilizată de Reddit include multe elemente comune cu GitHub, așa că, dacă ești deja expert în Markdown pentru repozitorii, transferul acestor cunoștințe în mediul Reddit este destul de simplu. Poți folosi titluri pentru a structura postări lungi, liste numerotate sau cu marcatori, citate pentru a răspunde altor utilizatori și blocuri de cod atunci când dorești să afișezi comenzi sau fragmente tehnice.

Una dintre diferențele notabile este modul în care Reddit gestionează... imaginiDeși în multe cazuri imaginile sunt încărcate prin interfața grafică și nu direct cu sintaxa Markdown, motorul care procesează conținutul text este tot Snoomark, așadar formatarea din jurul acelor imagini se bazează pe Markdown.

Reddit, pe de altă parte, adaugă elemente suplimentare care nu fac parte din specificația standard, cum ar fi spoilerele. Acestea vă permit să ascundeți textul în spatele unui strat pe care utilizatorul îl poate dezvălui cu un clic. Din punct de vedere tehnic, atunci când Reddit procesează un spoiler, îl transformă într-o combinație de HTML, clase CSS și JavaScript specific platformei.

Reprezentarea HTML rezultată a unui spoiler include handlere care controlează când să se afișeze sau să se ascundă conținutul și, deși teoretic ceva similar ar putea fi scris cu HTML simplu, pe Reddit depinde de implementarea sa internă. Important pentru tine, ca utilizator, este că, atunci când scrii, trebuie doar să folosești sintaxa specifică pentru spoiler furnizată de editor și Snoomark se ocupă de traducerea acestuia la structura corespunzătoare.

Pe scurt, Snoomark moștenește multe comportamente de la GitHub Flavored Markdown, dar este orientat către nevoile unei comunități de discuții mai degrabă decât către documentația proiectului. Chiar și așa, nucleul rămâne același: text simplu cu simboluri simple transformate în conținut structurat și ușor de citit.

Stăpânirea sintaxei Markdown pe GitHub și Reddit face mult mai eficiente scrierea documentației tehnice, deschiderea problemelor bine explicate, lăsarea de comentarii clare la solicitările de extragere și participarea la discuțiile de pe Reddit. Cu câteva reguli cheie - titluri, accentuare, liste, citate, blocuri de cod, linkuri, imagini și trucuri specifice precum tabele, detalii restrângibile, alerte, note de subsol și spoilere - puteți trece de la scrierea de text simplu la crearea de... conținut curat, scanabil și profesional fără a atinge niciun buton al mouse-ului.