Hur man snabbt använder Markdown på GitHub och Reddit

Informatec Digital » Resurser » Hur man snabbt använder Markdown på GitHub och Reddit

Om du ofta skriver på GitHub eller spenderar mycket tid på Reddit, är det en av de saker som sparar timmar och gör ditt liv enklare att bemästra Markdown . Det är ett väldigt lätt markupspråk som låter dig snabbt formatera vanlig text utan att krångla med menyer eller knappar, bara med några få symboler placerade på rätt ställen.

På GitHub hittar du det överallt: i arkivet README.md- filer , i ärenden, pull requests, diskussioner och till och med i din egen profil. Reddit, å andra sidan, använder en variant som heter Snoomark (Reddit-liknande Markdown) som ärver mycket av GitHubs syntax, med några unika funktioner och begränsningar. Låt oss se, steg för steg och med många exempel, hur man använder Markdown på GitHub och Reddit snabbt och utan att missa något viktigt.

Vad är Markdown och varför är det så användbart på GitHub och Reddit?

Markdown är ett lättviktigt markupspråk utformat för att göra vanlig text lätt att läsa och skriva, samtidigt som det möjliggör enkel konvertering till HTML. I praktiken innebär det att du kan skriva vanlig text och lägga till några specialtecken för att skapa rubriker, listor, tabeller, citat, formaterad kod, länkar eller bilder.

På GitHub används implementationen GitHub Flavored Markdown (GFM), som utökar den klassiska syntaxen med tabeller, att-göra-listor, avancerad kodmarkering, färgstöd, varningar och vissa tillåtna HTML-taggar. Allt detta renderas automatiskt i .md-filer och i plattformens kommentarfält.

Reddit använder sin egen editor som heter Snoomark, en derivat av GFM. Den delar mycket av det grundläggande beteendet (fetstil, kursiv stil, rubriker, listor, citat, inline- eller blockkod, länkar, etc.), men har viktiga särdrag : till exempel är bildstödet mer begränsat beroende på sammanhanget, och den lägger till egna element som spoilers.

Det fina med allt detta är att du med en enda syntax kan skriva texter som ser bra ut på både GitHub och Reddit, och bara anpassa några få detaljer där varje plattform fungerar olika. Genom att lära dig de grundläggande reglerna kan du navigera i båda med lätthet utan att behöva lära dig något från grunden.

Rubriker och innehållsstruktur

En av de första sakerna du kommer att använda är rubriker , både på GitHub och Reddit. De hjälper till att strukturera texten i avsnitt och underavsnitt.

I Markdown skapas en rubrik genom att föregå texten med en till sex hash-symboler: en för en rubrik på nivå 1, två för nivå 2, och så vidare upp till nivå 6. Till exempel, i en GitHub README.md-fil kan du ha något i stil med: # Huvudtitel , ## Avsnitt , ### Underavsnitt , etc.

När GitHub hittar två eller fler rubriker i en fil genereras automatiskt en innehållsförteckning som är tillgänglig via ikonen "Disposition" högst upp i filen. Varje rubrik visas som en länk som tar dig direkt till det avsnittet, vilket är bra för långa dokument.

Dessutom blir varje rubrik ett internt ankare som du kan länka till med ett URL-snutt baserat på titeltexten. För att generera det snuttet tillämpar GitHub mycket specifika regler: den konverterar bokstäver till gemener, ersätter mellanslag med bindestreck, tar bort skiljetecken och formateringstecken (som kursiv stil), trimmar överflödiga mellanslag och, om resultatet matchar en annan tidigare rubrik, lägger den till ett numeriskt suffix (-1, -2, etc.) för att göra den unik.

Detta låter dig göra saker som att placera ett ## exempelavsnitt och sedan länka till det från en annan punkt i dokumentet med en länk som (#exempelavsnitt) , eller till och med länka till avsnitt med specialtecken i titeln, eftersom GitHub genererar kodavsnittet enligt dessa regler och gör det tillgängligt med samma mönster.

Betoning, markerad text och citat

Med Markdown kan du markera text med olika former av betoning : fetstil, kursiv stil, genomstruken stil, nedsänkt stil, upphöjd stil eller understrykning. På GitHub skulle den typiska stiltabellen se ut ungefär så här, även om vi har sammanfattat den här med andra termer:

För att göra text fetstil , omge den med dubbla asterisker eller dubbla understreck; för kursiv stil, använd enkla asterisker eller understreck; för att stryka, använd en dubbel tilde (två tilde) på vardera sidan av texten. Du kan också kombinera kapslade fetstilar och kursiv stil, använda tre asterisker för att tillämpa båda på en hel textsektion, eller använda HTML-taggar som `<b>` _{för ^{nedsänkta och upphöjda tecken, och `<i>` för understreck.}}

GitHub låter dig också skapa blockcitat genom att placera ett större än-tecken (>) i början av raden. Den citerade texten visas med ett vertikalt streck till vänster och i grått, vilket gör att den framträder tydligt. Du kan ha flera rader inom samma blockcitat, och till och med kapsla citat genom att lägga till fler >-symboler i början.

En avancerad form av citering som är unik för GitHub är alert eller admonition . Den använder samma blockquote-syntax, men den första raden innehåller en speciell markör för att indikera typen av varning. Du kan till exempel ange "alert" för användbar information, "helpful tips", "key data", "urgent warnings" och "warnings of risks or negative consequences". GitHub visar varje typ med en annan färg och ikon, vilket hjälper till att markera viktig information i din dokumentation.

Reddit stöder även enkla citattecken med samma >-symbol, även om det saknar GitHubs omfattande pingsystem. Ändå är det fortfarande ett mycket användbart sätt att svara någon genom att citera en del av deras meddelande utan att upprepa det helt.

Kodmarkering, block och färger

Både GitHub och Reddit låter dig markera kodavsnitt i text med hjälp av backticks. För inline-kod omsluter du ordet eller kommandot med en enda backtick på varje sida. Detta är idealiskt för att markera till exempel " git status" i en mening, vilket gör det tydligt att det är ett kommando.

När du vill ha ett fristående kodblock använder Markdown tre backticks: du skriver en rad med tre backticks, sedan koden på separata rader och avslutar med ytterligare tre backticks. Om du på GitHub också anger språket direkt efter de första backticks, tillämpas syntaxmarkering med färger och formatering specifik för det språket.

GitHub erbjuder också en specifik funktion för att markera färgvärden i backticks. Om du skriver en färg i hexadecimalt, RGB- eller HSL-format mellan backticks, inkluderar plattformen en liten färgindikator bredvid texten. Om bakgrundsfärgen i ljust läge till exempel är #ffffff och i mörkt läge är #000000, kan du snabbt se vilken som är vilken genom att markera dessa koder.

När det gäller kod- och tabellvisning låter GitHub dig aktivera ett fast monospace-teckensnitt i alla kommentarfält, vilket gör det enklare att arbeta med teknisk text. Om du redigerar många kodavsnitt i din webbläsare eller i redigerare som Visual Studio Code , gör aktivering av det här alternativet justering och läsbarhet mycket mer konsekvent.

Reddit stöder också kodblock med backticks, både inline och block, även om deras användning där är mer fokuserad på små snippets eller pseudokod än på lång dokumentation som den i ett repository.

Länkar, ankare och intern navigering

Att skapa länkar i Markdown är väldigt enkelt: du omger texten som ska visas för användaren inom hakparenteser och URL:en inom parenteser. Detta fungerar på både GitHub och Reddit, och kan förbättras med kortkommandon på GitHub (till exempel genom att använda tangentkombinationer för att snabbt konvertera markerad text till en länk).

GitHub lägger till några extra navigeringsrelaterade funktioner. För det första låter det dig länka direkt till rubriker med hjälp av de regler för generering av kodavsnitt som diskuterats tidigare. För det andra stöder det relativa länkar inom själva arkivet, vilket är avgörande för teknisk dokumentation.

En relativ länk är en som beräknas med den aktuella filen som referens. Om till exempel din README-fil finns i projektets rotfil och du vill länka till filen docs/CONTRIBUTING.md, skriver du helt enkelt en länk med sökvägen docs/CONTRIBUTING.md. GitHub hanterar korrekt översättning av denna relativa länk i vilken gren du än är på, vilket förhindrar att den bryts när du byter gren eller klonar arkivet.

Rekommendationen är att alltid använda relativa sökvägar när man navigerar mellan filer i samma repository, eftersom absoluta länkar kan sluta fungera i kloner eller forks. GitHub tillåter användning av standardoperatorer som ./ eller ../ och sökvägar som börjar med / relativt till projektets rot.

Om du vill skapa anpassade ankarpunkter i ett dokument utöver rubriker kan du använda HTML-taggar med attributet `name`. Detta låter dig placera en målpunkt mitt i ett stycke eller bredvid text som inte har någon egen titel och länka till den med samma syntax som för automatiskt genererade rubriker.

Bilder på GitHub: Markdown, HTML och relativa sökvägar

På GitHub bäddas bilder vanligtvis in med samma syntax som länkar, men föregås av ett utropstecken. Alternativtexten (alt) anges inom hakparenteser och URL:en eller sökvägen till bilden placeras inom parenteser. Denna alternativtext är viktig för tillgängligheten , eftersom det är vad skärmläsare kommer att läsa och vad som kommer att visas om bilden inte laddas.

Bilder kan komma från filer inom själva arkivet eller från externa URL:er. GitHub tillåter flera relativa sökvägsmönster för att ladda upp bilder från olika grenar, andra arkiv eller till och med ärenden och kommentarer, med hjälp av suffix som ?raw=true för att tvinga fram en direkt filnedladdning vid behov.

Utöver standard Markdown-syntax stöder GitHub användningen av HTML-elementet `<picture>`. Detta element är särskilt användbart för att ladda responsiva bilder som ändras enligt användarens temainställningar (ljusa eller mörka). Med hjälp av mediefrågan `prefers-color-scheme` kan du definiera olika bildkällor för varje läge och en standardbild för webbläsare som inte stöder den här funktionen.

Det typiska mönstret innebär att inkludera inom flera element med dess media- och srcset-attribut, och slutligen en Med hjälp av alt-attributet och en generisk URL ser användare i mörkt läge en anpassad bild, medan de i ljust läge får en annan, utan att behöva duplicera innehåll i README-filen.

GitHub stöder även HTML-kommentarer i Markdown-filer, vilket gör att du kan lägga till osynliga påminnelser till läsaren, till exempel för att påminna dem om att uppdatera ett bildavsnitt eller lägga till nya exempel senare.

Tabeller, utfällbara sektioner och innehållsseparation

En av de mest användbara förbättringarna i GitHub Flavored Markdown är dess tabellstöd . Du kan organisera data i rader och kolumner med hjälp av vertikala streck för att separera celler och en rad med bindestreck för att markera rubriken. Det är också möjligt att justera kolumner till höger, vänster eller centrera med hjälp av ett kolon i avgränsarraden.

Tabeller är mycket användbara för att presentera listor över programmeringsspråk, använda ramverk, planerade uppgifter, funktionsjämförelser eller annan information som drar nytta av en matrisstruktur. GitHub renderar dessa tabeller med en ren och läsbar stil.

För att hålla en lång README-fil organiserad kan du använda HTML-taggen `<details>` för att skapa hopfällbara avsnitt. Dessa avsnitt visar en sammanfattning i `<summary>`-taggen och låter användaren expandera eller hopfälla ytterligare innehåll efter behov. Det är vanligt att omsluta tabeller eller block med sekundär information i `<details>` för att undvika att överväldiga användaren vid första anblicken.

Om du vill att avsnittet ska visas utökat som standard lägger du helt enkelt till attributet open Den här tekniken är mycket praktisk för att gruppera rankningar, långa listor eller innehåll som inte är nödvändigt för en första läsning men som är praktiskt att ha tillgängligt.

Ett annat enkelt verktyg för att organisera information är den horisontella regeln. Den skapas genom att skriva tre eller fler streck på en linje och tjänar till att dra en skiljelinje mellan avsnitt, vilket gör att du tydligt kan skilja till exempel ett beskrivande avsnitt från ett avsnitt med referenser eller ytterligare anteckningar.

Dessa regler kan kombineras med citat i slutet av dokumentet för att lyfta fram inspirerande fraser, påminnelser eller viktiga budskap. Ett typiskt exempel skulle vara att placera ett motiverande citat i slutet av din profils README-fil, formaterat med ett blockcitat efter en avgränsningsrad.

Dolda kommentarer och formatkontroll

GitHub låter dig infoga HTML-kommentarer i Markdown med syntaxen <!-- comment -->. Allt du skriver in i kommentaren visas inte i det renderade innehållet, men det syns i källkoden, vilket gör det idealiskt för interna anteckningar eller att-göra-uppgifter.

Till exempel kan du i en README-fil för profilen lägga till en kommentar som säger något i stil med att du behöver utöka avsnittet "Om mig" senare eller att du behöver granska en tabell över föråldrade tekniker, utan att någon som besöker profilen ser det direkt.

En annan användbar funktion är escape-tecken som normalt skulle tolkas som Markdown. Om du behöver visa asterisker, hash-symboler eller andra symboler bokstavligt utan att de är formaterade, skriv helt enkelt ett omvänt snedstreck före varje symbol. Detta gör att du till exempel kan skriva uttryck som innehåller listsymboler utan att konvertera dem till faktiska listor.

När du visar en markup-fil på GitHub kan du växla mellan den renderade vyn och källkoden med en knapp högst upp (eller öppna den i redigerare som Brackets ). Om du inaktiverar Markdown-tolkning får du tillgång till typiska kodvyfunktioner som att länka specifika rader , vilket är mycket användbart när du vill markera ett exakt avsnitt i en README- eller .md-fil.

Slutligen, kom ihåg att GitHub hanterar radbrytningar olika i kommentarer (problem, PR, etc.) och i .md-filer. I kommentarer respekteras radbrytningar direkt, medan du i Markdown-filer behöver lägga till två mellanslag i slutet av raden, ett omvänt snedstreck eller en punkt. för att tvinga fram hoppet inom samma stycke.

Listor, kapslade listor och att-göra-listor

Listor är ett av de vanligaste elementen i Markdown, både på GitHub och Reddit. Du kan skapa oordnade listor genom att föregå varje listobjekt med ett bindestreck, en asterisk eller ett plustecken. Alla dessa markörer återges på liknande sätt som punktlistor.

För att generera ordnade listor , numrera varje rad med ett nummer följt av en punkt och ett mellanslag. Även om ordningen på siffrorna inte behöver vara perfekt (GitHub brukar räkna om den), är det en bra idé att bibehålla en konsekvent numrering för att hålla källkoden läsbar.

Kapslade listor skapas helt enkelt genom att indentera objekten under dem. I redigerare med fast radavstånd som Sublime Text behöver du bara visuellt justera de kapslade listmarkörerna under det första tecknet i texten i det överordnade objektet. I sammanhang som kommentarredigeraren i GitHub, där teckensnittet inte är med fast radavstånd, bör du räkna hur många tecken som finns före texten och använda det antalet mellanslag för indenteringen.

Du kan också bygga flera nivåer av kapsling, så länge du bibehåller ett konsekvent antal mellanslag. För mycket komplexa listor kräver det här systemet lite övning, men när du väl fått kläm på det går det väldigt snabbt att tillämpa.

GitHub erbjuder även uppgiftslistor , vilka är mycket användbara för ärenden, pull requests och dokumentation. Dessa skapas genom att listan skrivs med ett bindestreck, ett mellanslag och ett par hakparenteser med ett mellanslag eller ett "x" inuti: en för väntande uppgifter och en för slutförda uppgifter. Dessa listor visas med kryssrutor som kan markeras eller avmarkeras från gränssnittet.

Om texten i en att-göra-lista börjar med parenteser måste den omvändas med ett omvänt snedstreck för att undvika förvirring i tolken. Det är en liten detalj, men viktig när man skriver beskrivningar som börjar med något i stil med "(Valfritt)" eller liknande.

Omnämnanden, referenser och emojis på GitHub

En av fördelarna med att skriva i Markdown på GitHub är möjligheten att använda direkta omnämnanden av användare och team på plattformen. Du skriver helt enkelt @ följt av användarnamnet eller teamnamnet, och GitHub skickar en avisering till det kontot och riktar deras uppmärksamhet mot konversationen.

När du skriver @-tecknet visar GitHub en lista över användare och team som är kopplade till arkivet eller tråden, och du kan filtrera listan medan du skriver. Använd piltangenterna och tryck på Enter eller Tab för att acceptera förslagen. För team, använd formatet @organisation/teamnamn, så prenumererar alla teammedlemmar på tråden.

Förutom omnämnanden gör GitHub det enkelt att referera till ärenden och pull requests genom att helt enkelt skriva # följt av en siffra eller en del av titeln. En lista med föreslagna resultat visas, som du kan fylla i på samma sätt som med omnämnanden. Detta snabbar upp navigeringen mellan relaterade konversationer avsevärt.

Om ditt arkiv har anpassade autolänkade referenser konfigurerade kan vissa externa notationer (som JIRA- eller Zendesk-ärende-ID:n) också konverteras automatiskt till korta länkar. Den här inställningen kräver administratörsbehörighet, men när den är aktiverad möjliggör den datadelning mellan system med minimal ansträngning.

Slutligen stöder GitHub emojis via kod: skriv ett kolon, följt av emojins namn och avsluta med ytterligare ett kolon. När du börjar skriva visas en lista med förslag som du kan acceptera med Tab eller Enter. Att införliva emojis i dina kommentarer ger dem en mer mänsklig touch, så länge du inte överanvänder dem i formell dokumentation.

Fotnoter och avancerat innehåll

GitHub stöder även fotnoter med hjälp av en parentesbaserad syntax och en identifierare med ett cirkumfletstecken. Där du vill ha referensen infogar du något i stil med `<fotnot>`, och i slutet av dokumentet definierar du texten i fotnoten med samma tagg, följt av ett kolon och innehållet.

Fotnoter kan sträcka sig över flera rader, och för att tvinga fram radbrytningar inom en fotnot används dubbla mellanslag i slutet av raden, precis som i huvuddelen av Markdown. Vid rendering visar GitHub en upphöjd text och en lista med fotnoter i slutet, med bakåtlänkar för att navigera mellan referenser och fotnoter.

En annan avancerad funktion som erbjuds av GitHub är de tidigare nämnda varningarna (OBS, TIPS, VIKTIGT, VARNING och VARNING). Det är lämpligt att bara använda dem när det verkligen är nödvändigt och att undvika att kedja ihop för många för att förhindra att läsaren blir överbelastad. De kan inte kapslas in i andra komplexa element, så noggrann planering är avgörande för deras placering.

Slutligen kan du be GitHub att tillfälligt dölja delar av renderad Markdown genom att omsluta dem i HTML-kommentarer, eller att ignorera bearbetningen av vissa tecken med bakåtsnedstreck. Detta är särskilt användbart när du dokumenterar själva Markdown-syntaxen och behöver visa exempel som de är, utan tolkning.

Markdown på Reddit: Snoomark och redigeringsläge

Reddit är en diskussionsplattform där nästan alla ämnen är välkomna, organiserade i subreddits. När det gäller formatering erbjuder den två redigerare: en för RTF som är mer visuell, och en annan för vanlig text baserad på Markdown. Om du vill arbeta snabbt och ha fin kontroll över resultatet bör du använda Markdown-alternativet.

Som standard aktiverar Reddit vanligtvis RTF-redigeraren, så för att växla till markeringsläge måste du klicka på alternativet Markdown-läge i textrutan i ett inlägg eller en kommentar. Därifrån kan du använda Snoomark-syntaxen direkt.

Om du föredrar att Markdown-redigeraren alltid laddas, gå till dina användarinställningar, öppna avsnittet Flödesinställningar och aktivera alternativet "Standard till Markdown" . På så sätt öppnas Markdown-redigeraren automatiskt varje gång du börjar skriva ett inlägg eller en kommentar, utan att du behöver ändra det manuellt.

Reddit stöder de flesta grundläggande och avancerade Markdown-funktioner: rubriker, fetstil och kursiv stil, listor, citat, kodblock, länkar och några av sina egna extrafunktioner som spoilers. Det har dock betydande brister jämfört med GitHub, särskilt i bildhantering , som är starkt beroende av kontext och typ av redigerare.

Syntax som stöds av Reddit och spoilers

Snoomark-varianten som används av Reddit innehåller många element som är gemensamma med GitHub, så om du redan är skicklig på Markdown för repositories är det ganska enkelt att överföra den kunskapen till Reddit-miljön. Du kan använda rubriker för att strukturera långa inlägg, numrerade eller punktlistor, citat för att svara andra användare och kodblock när du vill visa kommandon eller tekniska utdrag.

En av de anmärkningsvärda skillnaderna är hur Reddit hanterar bilder . Även om bilder i många fall laddas upp via det grafiska gränssnittet och inte direkt med Markdown-syntax, är motorn som bearbetar textinnehållet fortfarande Snoomark, så formateringen kring dessa bilder är verkligen baserad på Markdown.

Reddit, å andra sidan, lägger till extra funktioner som inte ingår i standardspecifikationen, såsom spoilers. Dessa gör att text kan döljas bakom ett lager som användaren kan visa med ett klick. Tekniskt sett, när Reddit bearbetar en spoiler, omvandlas den till en kombination av HTML, CSS-klasser och plattformsspecifik JavaScript.

Den resulterande HTML-representationen av en spoiler inkluderar hanterare som styr när innehållet ska visas eller döljas, och även om något liknande teoretiskt sett skulle kunna skrivas med vanlig HTML, beror det på Reddit på dess interna implementering. Det viktiga för dig som användare är att du, när du skriver, bara behöver använda den specifika spoilersyntaxen som tillhandahålls av redigeraren, och Snoomark tar hand om att översätta den till lämplig struktur.

Kort sagt, Snoomark ärver många beteenden från GitHub Flavored Markdown, men anpassat till behoven hos en diskussionsgemenskap snarare än projektdokumentation. Kärnan är dock densamma: vanlig text med enkla symboler omvandlade till strukturerat och läsbart innehåll.

Att behärska Markdown-syntax på GitHub och Reddit gör det mycket effektivare att skriva teknisk dokumentation, öppna välförklarade ärenden, lämna tydliga kommentarer på pull requests och delta i Reddit-diskussioner. Med några få nyckelregler – rubriker, betoning, listor, citat, kodblock, länkar, bilder och specifika knep som tabeller, hopfällbara detaljer, varningar, fotnoter och spoilers – kan du gå från att skriva intetsägande meddelanden till att skapa rent, skannbart och professionellt innehåll utan att klicka på en enda musknapp.