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 regelbundet skriver på GitHub eller spenderar mycket tid på Reddit, att bemästra Markdown Det är en av de saker som sparar timmar och gör ditt liv enklare. Det är ett väldigt lätt markupspråk som låter dig formatera vanlig text snabbt, utan att behöva kämpa med menyer eller knappar, bara med några få symboler placerade på rätt ställen.

På GitHub hittar du det överallt: i filerna README.md från repositorier, problem, pull requests, diskussioner och till och med din egen profil. Reddit använder för sin del en variant som heter Snoomark (Reddit-liknande Markdown) som ärver mycket av GitHubs syntax, med några unika funktioner och vissa begränsningar. Låt oss se, steg för steg och med många exempel, Hur man snabbt använder Markdown på GitHub och Reddit och utan att utelämna något viktigt.

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

Markdown är en lättviktsmarkeringsspråk Utformad för att göra vanlig text lätt att läsa och skriva, samtidigt som den möjliggör enkel konvertering till HTML. I praktiken innebär det att du kan skriva vanlig text och lägga till 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 återges automatiskt i .md-filerna och i plattformens kommentarsfält.

Reddit använder sin egen processor som heter Snoomark, en derivata av GFM. Den delar mycket av det grundläggande beteendet (fetstil, kursiv stil, rubriker, listor, citat, inline- eller blockkod, länkar etc.), men den har viktiga funktionerTill exempel är bildstödet mer begränsat beroende på sammanhanget och 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. Lär dig de grundläggande reglerna Det låter dig röra dig fritt i båda 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 headersBåde på GitHub och Reddit används de för 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, ### UnderavsnittEtc.

När GitHub hittar två eller fler rubriker i en fil genereras automatiskt en innehållstabell Tillgänglig från 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: det 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ägga till ett numeriskt suffix (-1, -2, etc.) för att göra den unik.

Detta låter dig göra saker som att placera en sektion ## Exempelavsnitt och sedan länka till den från en annan punkt i dokumentet med en länk som denna: (#exempel-avsnitt)eller ens 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

Markdown låter dig markera text med olika metoder betoningFet, kursiv, genomstruken, nedsänkt, upphöjd eller understruken. På GitHub skulle den typiska stiltabellen se ut ungefär så här, även om vi har sammanfattat den här med andra ord:

Att lägga in text fetstilFet text omges av dubbla asterisker eller dubbla understreck; för kursiv stil används enkla asterisker eller understreck; för att stryka över något placeras en dubbel tilde (två tilde) på vardera sidan av texten. Kapslade fetstilar och kursiv stil kan också kombineras, tre asterisker kan användas för att tillämpa båda på ett helt textavsnitt, eller så kan HTML-taggar som <br> användas. _{y ^{för index och upphöjda tecken, och för understrykning.}}

GitHub låter dig också skapa citat i blockcitatstil Genom att placera större än-tecknet (>) i början av raden visas den citerade texten med ett vertikalt streck till vänster och i grått, vilket gör att den framträder tydligt. Flera rader kan inkluderas i samma citatblock, och citat kan till och med kapslas genom att lägga till fler >-symboler i början.

En avancerad form av citering som bara finns på GitHub är varningar eller förmaningarDe är baserade på samma blockquote-syntax, men den första raden innehåller en speciell markör som anger typen av varning. Du kan till exempel ange `<varning>` för användbar information, `<användbara tips>` för praktiska råd, `<nyckeldata>` för nyckeldata, `<brådskande meddelanden>` för brådskande varningar och `<varning>` för varningar om risker eller negativa konsekvenser. GitHub visar varje typ med en annan färg och ikon, vilket hjälper till att markera viktig information i dokumentationen.

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

Kodmarkering, block och färger

Både GitHub och Reddit låter dig markera kodavsnitt i texten 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 en git status i en mening, vilket gör det tydligt att det är en befallning.

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. På GitHub, om du också anger språket direkt efter de första backticks, gäller det... syntaxmarkering med färger och format som är specifika för det språket.

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

När det gäller kod- och tabellvisualisering låter GitHub dig aktivera ett fast monospace-teckensnitt i alla kommentarfält för att göra det bekvämare att arbeta med teknisk text. Om du redigerar många kodavsnitt i din webbläsare eller i redigerare som Visual Studio CodeAtt aktivera det här alternativet gör det enklare att justera och läsa. mycket mer sammanhängande.

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 funktioner relaterade till navigering. För det första tillåter det länka direkt till rubriker med hjälp av de fragmentgenereringsregler som diskuterats tidigare. Dessutom stöder den relativa länkar inom själva arkivet, vilket är avgörande i 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 vägar För att navigera mellan filer inom samma repository, eftersom absoluta länkar kan sluta fungera i kloner eller forks, tillåter GitHub användning av standardoperatorer som ./ eller ../ och sökvägar som börjar med / i förhållande till projektroten.

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ängligheteftersom 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 i 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 ?rå=sant för att tvinga fram direkt nedladdning av filen vid behov.

Förutom standard Markdown-syntax stöder GitHub användningen av HTML-elementet Denna artikel är särskilt användbar för laddning responsiva bilder Dessa ändras beroende på användarens temainställningar (ljust eller mörkt). Med hjälp av mediafrå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 stöd för ritaDu kan organisera data i rader och kolumner med hjälp av vertikala streck för att separera celler och en streckad linje för att markera rubriken. Du kan också justera kolumner till höger, vänster eller centrera med hjälp av ett kolon i avgränsningsraden.

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 för att skapa hopfällbara avsnitt. Dessa avsnitt visar en sammanfattning inom etiketten och låta användaren expandera eller krympa ytterligare innehåll efter behov. Det är vanligt att omsluta tabeller eller block med sekundärinformation för att undvika att överbelasta ögat.

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 introducera HTML-kommentarer inom Markdown med hjälp av syntaxen Allt du skriver i kommentaren kommer inte att visas i det renderade innehållet, men det kommer att synas i källkoden, så det är 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 att flyktkaraktärer vilket normalt skulle tolkas som Markdown. Om du behöver visa asterisker, hashsymboler eller andra symboler bokstavligt utan att de är formaterade, föregås var och en med ett omvänt snedstreck. Detta låter dig till exempel skriva uttryck som innehåller listsymboler utan att konvertera dem till faktiska listor.

När du visar en markup-fil på GitHub har du möjlighet att växla mellan den renderade vyn och källkoden med en knapp högst upp (eller öppna den i redigerare som KonsolerOm du inaktiverar Markdown-tolkning får du tillgång till typiska kodvyfunktioner som länkspecifika raderDetta är mycket användbart när du vill peka på en exakt del av en README- eller någon .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 mest använda elementen i Markdown, både på GitHub och Reddit. Du kan skapa listor oordnad genom att placera ett bindestreck, en asterisk eller ett plustecken före varje listobjekt. Alla dessa markeringar återges på liknande sätt som punktlistor.

Att generera listor beordradeVarje rad är numrerad 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 göra källkoden läsbar.

Kapslade listor skapas helt enkelt genom att lägga till indentering till objekten under dem. I redigerare med fast radavstånd som Sublima TextJustera helt enkelt de kapslade listmarkörerna visuellt under det första tecknet i texten i det överordnade elementet. I sammanhang som kommentarredigeraren i GitHub, där teckensnittet inte är med fast radavstånd, räkna antalet tecken före texten och använd det antalet mellanslag för indentering.

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 att göra-listorDessa är mycket användbara för ärenden, pull requests och dokumentation. De skapas genom att föregå ett bindestreck, ett mellanslag och ett par hakparenteser med ett mellanslag eller ett "x" inuti: för väntande uppgifter och för slutförda uppgifter. Dessa listor återges 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 att kunna använda nämner Direktmeddelanden till användare och team på plattformen. Skriv bara @ följt av användarnamnet eller teamnamnet, så skickar GitHub ett meddelande till det kontot och uppmärksammar dem på 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 underlättar GitHub referensproblem och pull requests Skriv bara # 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 sammanflätat tecken. Där du vill ha referensen infogar du något i stil med , och i slutet av dokumentet definierar du texten i den anteckningen 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 GitHub erbjuder är... varningar Dessa har redan diskuterats (OBS, TIPS, VIKTIGT, VARNING och VARNING). Det är lämpligt att endast använda dem när det verkligen är nödvändigt och att undvika att lägga ihop för många för att inte överbelasta läsaren. De kan inte kapslas in i andra komplexa element, så noggrann planering av deras placering är avgörande.

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. Markdowns egen syntax Och du måste visa exemplen 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 markuplä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 Snoomarks syntax direkt.

Om du föredrar att Markdown-redigeraren alltid laddas, gå till användarinställningar, öppna avsnittet Flödesinställningar och aktivera alternativet Standardinställning för nedsättningPå 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 den 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 hantering av bildervilket beror ganska mycket på sammanhanget och typen av redaktör.

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 bildspråkÄ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 baserad på Markdown.

Reddit, å andra sidan, tillägger ytterligare element som inte ingår i standardspecifikationen, såsom spoilers. Dessa låter dig dölja text 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 spoilersyntax som tillhandahålls av redigeraren, och Snoomark ansvarar för översättningen 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 problem, 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 vanlig text till att skapa... rent, skannbart och professionellt innehåll utan att röra en enda musknapp.