Slik bruker du Markdown raskt på GitHub og Reddit

Informatec Digital » Ressurser » Slik bruker du Markdown raskt på GitHub og Reddit

Hvis du regelmessig skriver på GitHub eller bruker mye tid på Reddit, er det viktig å mestre Markdown Det er en av de tingene som sparer deg timer og gjør livet enklere. Det er et veldig lett markupspråk som lar deg formatere ren tekst raskt, uten å slite med menyer eller knapper, bare med noen få symboler plassert på de riktige stedene.

På GitHub finner du det overalt: i filene README.md fra repositorier, problemer, pull-forespørsler, diskusjoner og til og med din egen profil. Reddit bruker på sin side en variant kalt Snoomark (Reddit-stil Markdown) som arver mye av GitHubs syntaks, med noen unike funksjoner og visse begrensninger. La oss se, trinn for trinn og med mange eksempler, Slik bruker du Markdown raskt på GitHub og Reddit og uten å utelate noe viktig.

Hva er Markdown, og hvorfor er det så nyttig på GitHub og Reddit?

Markdown er en lettvekts markupspråk Utviklet for å gjøre ren tekst enkel å lese og skrive, samtidig som det muliggjør enkel konvertering til HTML. I praksis betyr dette at du kan skrive vanlig tekst og legge til spesialtegn for å lage overskrifter, lister, tabeller, sitater, formatert kode, lenker eller bilder.

På GitHub brukes implementeringen GitHub Flavored Markdown (GFM), som utvider den klassiske syntaksen med tabeller, gjøremålslister, avansert kodeutheving, fargestøtte, varsler og noen tillatte HTML-tagger. Alt dette gjengis automatisk i .md-filene og i plattformens kommentarfelt.

Reddit bruker sin egen prosessor kalt Snoomark, en derivat av GFM. Den deler mye av den grunnleggende oppførselen (fet skrift, kursiv, overskrifter, lister, sitater, innebygd eller blokkkode, lenker osv.), men den har viktige funksjonerFor eksempel er bildestøtte mer begrenset avhengig av konteksten og legger til egne elementer som spoilere.

Det fine med alt dette er at du med én syntaks kan skrive tekster som ser bra ut på både GitHub og Reddit, og bare tilpasse noen få detaljer der hver plattform fungerer forskjellig. Lær de grunnleggende reglene Det lar deg bevege deg fritt i begge uten å måtte lære noe på nytt fra bunnen av.

Overskrifter og innholdsstruktur

Noe av det første du bruker er overskrifterBåde på GitHub og Reddit brukes de til å strukturere teksten i seksjoner og underseksjoner.

I Markdown opprettes en overskrift ved å sette ett til seks hash-symboler foran teksten: ett for en overskrift på nivå 1, to for nivå 2, og så videre opp til nivå 6. For eksempel, i en GitHub README.md-fil kan du ha noe sånt som: # Hovedtittel, ## Seksjon, ### UnderavsnittOsv

Når GitHub finner to eller flere overskrifter i en fil, genererer den automatisk en innholdsfortegnelse Tilgjengelig fra «Oversikt»-ikonet øverst i filen. Hver overskrift vises som en lenke som tar deg direkte til den delen, noe som er flott for lange dokumenter.

I tillegg blir hver overskrift et internt anker som du kan lenke til med et URL-snutt basert på tittelteksten. For å generere dette snuttet bruker GitHub svært spesifikke regler: den konverterer bokstaver til små bokstaver, erstatter mellomrom med bindestreker, fjerner tegnsetting og formateringstegn (som kursiv), trimmer overflødige mellomrom, og hvis resultatet samsvarer med en annen tidligere overskrift, legge til et numerisk suffiks (-1, -2 osv.) for å gjøre den unik.

Dette lar deg gjøre ting som å plassere en seksjon ## Eksempelseksjon og deretter lenke til den fra et annet punkt i dokumentet med en lenke som denne: (#eksempel-seksjon)eller til og med lenke til seksjoner med spesialtegn i tittelen, siden GitHub genererer kodebiten etter disse reglene og gjør den tilgjengelig med samme mønster.

Utheving, uthevet tekst og sitater

Markdown lar deg markere tekst ved hjelp av ulike metoder vektFet, kursiv, gjennomstreket, senket, hevet eller understreket. På GitHub ville den typiske stiltabellen se omtrent slik ut, selv om vi har oppsummert den her med andre ord:

Å sette inn tekst fet skriftFet tekst er omsluttet av doble stjerner eller doble understrekninger; for kursiv brukes enkle stjerner eller understrekninger; for å stryke over noe plasseres en dobbel tilde (to tilder) på hver side av teksten. Nestede uthevede og kursive skrifter kan også kombineres, tre stjerner kan brukes til å gjelde begge deler for en hel tekstdel, eller HTML-koder som <br> kan brukes. _{y ^{for senket og hevet skrift, og for understrekning.}}

GitHub lar deg også lage sitater i blokksitatstil Ved å plassere større-enn-tegnet (>) i begynnelsen av linjen, vises den siterte teksten med en vertikal strek til venstre og i grått, noe som gjør at den fremstår tydelig. Flere linjer kan inkluderes i samme sitatblokk, og sitater kan til og med nestes ved å legge til flere >-symboler i begynnelsen.

En avansert form for sitering som bare finnes på GitHub er varsler eller formaningerDe er basert på samme blokksitatsyntaks, men den første linjen inneholder en spesiell markør for å angi typen varsel. Du kan for eksempel spesifisere `<varsel>` for nyttig informasjon, `<nyttige tips>` for praktiske råd, `<nøkkeldata>` for nøkkeldata, `<hastemeldinger>` for hastevarsler og `<varsel>` for advarsler om risikoer eller negative konsekvenser. GitHub viser hver type med en annen farge og et annet ikon, noe som bidrar til å fremheve kritisk informasjon i dokumentasjonen.

Reddit støtter også enkle anførselstegn med samme symbol >, selv om det mangler GitHubs omfattende varslingssystem. Likevel er det fortsatt en veldig nyttig måte å å svare noen ved å sitere deler av meldingen deres uten å gjenta det fullstendig.

Kodemarkering, blokker og farger

Både GitHub og Reddit lar deg markere kodestykker i teksten ved hjelp av backticks. For innebygd kode omslutter du ordet eller kommandoen med et enkelt backtick på hver side. Dette er ideelt for å markere for eksempel en git -status i en setning, noe som gjør det klart at det er en kommando.

Når du ønsker en frittstående kodeblokk, bruker Markdown tre backticks: du skriver en linje med tre backticks, deretter koden på separate linjer, og avslutter med ytterligere tre backticks. På GitHub, hvis du også spesifiserer språket rett etter de første backticksene, gjelder det... syntaks utheving med farger og formater som er spesifikke for det språket.

GitHub tilbyr også en spesifikk funksjon for å fremheve fargeverdier i bakgrunnstegn. Hvis du skriver en farge i heksadesimal-, RGB- eller HSL-format mellom bakgrunnstegn, inkluderer plattformen en liten fargeindikator ved siden av teksten. Hvis for eksempel bakgrunnen i lys modus er #ffffff og i mørk modus #000000, lar det deg raskt se hvilken som er hvilken ved å markere disse kodene.

Når det gjelder kode- og tabellvisualisering, lar GitHub deg aktivere en fast monospace-skrifttype i alle kommentarfelt for å gjøre det mer komfortabelt å jobbe med teknisk tekst. Hvis du redigerer mange kodebiter i nettleseren din eller i redigeringsprogrammer som Visual Studio CodeHvis du aktiverer dette alternativet, blir det enklere å justere og lese. mye mer sammenhengende.

Reddit støtter også kodeblokker med backticks, både inline og block, selv om bruken av dem der er mer fokusert på små snutter eller pseudokode enn på lang dokumentasjon som for et repository.

Lenker, ankere og intern navigasjon

Det er veldig enkelt å lage lenker i Markdown: du setter teksten som skal vises til brukeren i hakeparenteser og URL-en i parenteser. Dette fungerer både på GitHub og Reddit, og kan forbedres med hurtigtaster på GitHub (for eksempel ved å bruke tastekombinasjoner for raskt å konvertere merket tekst til en lenke).

GitHub legger til noen ekstra funksjoner knyttet til navigasjon. For det første tillater det lenke direkte til overskrifter ved hjelp av reglene for fragmentgenerering som ble omtalt tidligere. Videre støtter den relative lenker i selve depotet, noe som er avgjørende i teknisk dokumentasjon.

En relativ lenke er en som beregnes ved å bruke den gjeldende filen som referanse. Hvis for eksempel README-filen din er i prosjektroten og du vil lenke til filen docs/CONTRIBUTING.md, skriver du ganske enkelt en lenke med stien docs/CONTRIBUTING.md. GitHub håndterer korrekt oversettelse av denne relative lenken i enhver gren du er på, og forhindrer at den brytes når du bytter gren eller kloner depotet.

Anbefalingen er å alltid bruke relative veier For å navigere mellom filer i samme repository, fordi absolutte lenker kan slutte å virke i kloner eller forks, tillater GitHub bruk av standardoperatorer som ./ eller ../ og stier som starter med / i forhold til prosjektroten.

Hvis du vil opprette egendefinerte ankerpunkter i et dokument utover overskrifter, kan du bruke HTML-koder med `name`-attributtet. Dette lar deg plassere et målpunkt midt i et avsnitt eller ved siden av tekst som ikke har en egen tittel, og lenke til det ved hjelp av samme syntaks som for automatisk genererte overskrifter.

Bilder på GitHub: Markdown, HTML og relative stier

På GitHub legges bilder vanligvis inn med samme syntaks som lenker, men innledes med et utropstegn. Alternativ tekst (alt) er angitt i hakeparenteser, og URL-en eller banen til bildet er plassert i parenteser. Denne alternative teksten er viktig for tilgjengelighetfordi det er det skjermlesere vil lese og det som vil vises hvis bildet ikke lastes inn.

Bilder kan komme fra filer i selve depotet eller fra eksterne URL-er. GitHub tillater flere relative stimønstre for opplasting av bilder fra forskjellige grener, andre depoter eller til og med problemer og kommentarer, ved bruk av suffikser som ?rå=sann for å tvinge frem direkte nedlasting av filen når det er nødvendig.

I tillegg til standard Markdown-syntaks støtter GitHub bruk av HTML-elementet Denne varen er spesielt nyttig for lading responsive bilder Disse endres i henhold til brukerens temapreferanser (lys eller mørk). Ved å bruke mediespørringen `prefers-color-scheme` kan du definere forskjellige bildekilder for hver modus, og et standardbilde for nettlesere som ikke støtter denne funksjonen.

Det typiske mønsteret innebærer å inkludere innenfor flere elementer med media- og srcset-attributtene, og til slutt en Ved å bruke alt-attributtet og en generisk URL ser brukere i mørk modus et tilpasset bilde, mens de i lys modus får et annet, uten å måtte duplisere innhold i README-filen.

GitHub støtter også HTML-kommentarer i Markdown-filer, slik at du kan legge til usynlige påminnelser til leseren, for eksempel for å minne dem på å oppdatere en bildeseksjon eller legge til nye eksempler senere.

Tabeller, utbrettbare seksjoner og innholdsseparasjon

En av de mest nyttige forbedringene i GitHub Flavored Markdown er støtten for trekkeDu kan organisere data i rader og kolonner ved å bruke vertikale streker for å skille celler og en stiplet linje for å markere overskriften. Du kan også justere kolonner til høyre, venstre eller sentrert ved å bruke et kolon i skillelinjen.

Tabeller er svært nyttige for å presentere lister over programmeringsspråk, rammeverk som brukes, planlagte oppgaver, funksjonssammenligninger eller annen informasjon som drar nytte av en matrisestruktur. GitHub gjengir disse tabellene med en ren og lesbar stil.

For å holde en lang README-fil organisert, kan du bruke HTML-taggen for å opprette sammenleggbare seksjoner. Disse seksjonene viser et sammendrag i etiketten og la brukeren utvide eller trekke seg sammen tilleggsinnhold etter behov. Det er vanlig å legge ved tabeller eller blokker med sekundærinformasjon. for å unngå å overbelaste øyet.

Hvis du vil at seksjonen skal vises utvidet som standard, legger du bare til open-attributtet til Denne teknikken er veldig praktisk for å gruppere rangeringer, lange lister eller innhold som ikke er viktig for førstegangslesning, men som er praktisk å ha tilgjengelig.

Et annet enkelt verktøy for å organisere informasjon er den horisontale streken. Den lages ved å skrive tre eller flere bindestreker på en linje og tjener til å tegne en skillelinje mellom seksjoner, slik at du tydelig kan skille for eksempel en beskrivende seksjon fra en seksjon med referanser eller tilleggsnotater.

Disse reglene kan kombineres med sitater på slutten av dokumentet for å fremheve inspirerende fraser, påminnelser eller viktige budskap. Et typisk eksempel ville være å plassere et motiverende sitat på slutten av profilens README-fil, formatert med et blokksitat etter en skillelinje.

Skjulte kommentarer og formatkontroll

GitHub lar deg introdusere HTML-kommentarer i Markdown ved hjelp av syntaksen Alt du legger inn i den kommentaren vil ikke vises i det gjengitte innholdet, men det vil være synlig i kildekoden, så det er ideelt for interne notater eller gjøremål.

I en README-fil for profilen kan du for eksempel legge til en kommentar som sier noe sånt som at du må utvide «Om meg»-delen senere, eller at du må se gjennom en tabell over foreldede teknologier, uten at noen som besøker profilen ser den direkte.

En annen nyttig funksjon er at rømningsfigurer som normalt ville bli tolket som Markdown. Hvis du trenger å vise stjerner, hash-symboler eller andre symboler bokstavelig talt uten at de er formatert, setter du ganske enkelt en omvendt skråstrek foran hver av dem. Dette lar deg for eksempel skrive uttrykk som inkluderer listesymboler uten å konvertere dem til faktiske lister.

Når du ser på en markup-fil på GitHub, har du muligheten til å veksle mellom den gjengitte visningen og kildekoden med en knapp øverst (eller åpne den i redigeringsprogrammer som ParentesHvis du deaktiverer Markdown-tolkning, får du tilgang til typiske kodevisningsfunksjoner, som for eksempel lenkespesifikke linjerDette er veldig nyttig når du vil peke til en eksakt del av en README- eller en hvilken som helst .md-fil.

Til slutt, husk at GitHub håndterer linjeskift forskjellig i kommentarer (problemer, PR-er osv.) og i .md-filer. I kommentarer respekteres linjeskift direkte, mens i Markdown-filer må du legge til to mellomrom på slutten av linjen, en omvendt skråstrek eller et punktum. for å tvinge frem hoppet innenfor samme avsnitt.

Lister, nestede lister og gjøremålslister

Lister er et av de mest brukte elementene i Markdown, både på GitHub og Reddit. Du kan opprette lister uordnet ved å plassere en bindestrek, stjerne eller plusstegn foran hvert listeelement. Alle disse merkene gjengis på samme måte som punktlister.

Å generere lister bestiltHver linje er nummerert med et tall etterfulgt av et punktum og et mellomrom. Selv om rekkefølgen på tallene ikke trenger å være perfekt (GitHub beregner den vanligvis på nytt), er det lurt å opprettholde konsistent nummerering for å gjøre kildekoden lesbar.

Nestede lister opprettes ganske enkelt ved å legge til innrykk i elementene under dem. I redigeringsprogrammer med fast linjeavstand som Sublime TextBare juster de nestede listemarkørene visuelt under det første tegnet i teksten i det overordnede elementet. I kontekster som kommentarredigereren på GitHub, der skrifttypen ikke er med fast linjeavstand, teller du antall tegn før teksten og bruker det antallet mellomrom for innrykk.

Du kan også bygge flere nivåer av nesting, så lenge du opprettholder konsistens i antall mellomrom. For svært komplekse lister krever dette systemet litt øvelse, men når du først får taket på det, er det veldig raskt å bruke.

GitHub tilbyr også oppgavelisterDisse er svært nyttige for problemer, pull-forespørsler og dokumentasjon. De opprettes ved å sette et mellomrom eller en "x" foran en bindestrek, et mellomrom og et par hakeparenteser: for ventende oppgaver og for fullførte oppgaver. Disse listene gjengis med avmerkingsbokser som kan merkes av eller fjernes fra grensesnittet.

Hvis teksten i et gjøremålslisteelement begynner med parenteser, må det omgås med en omvendt skråstrek for å unngå forvirring i parseren. Det er en liten detalj, men viktig når man skriver beskrivelser som begynner med noe sånt som «(Valgfritt)» eller lignende.

Omtaler, referanser og emojier på GitHub

En av fordelene med å skrive i Markdown på GitHub er å kunne bruke nevner Direktemeldinger til brukere og team på plattformen. Bare skriv @ etterfulgt av brukernavnet eller teamnavnet, så sender GitHub et varsel til den kontoen og gjør dem oppmerksomme på samtalen.

Når du skriver @-tegnet, viser GitHub en liste over brukere og team som er tilknyttet depotet eller tråden, og du kan filtrere denne listen mens du skriver. Bruk piltastene og trykk Enter eller Tab for å godta forslagene. For team bruker du formatet @organisasjon/teamnavn, så abonnerer alle teammedlemmer på tråden.

I tillegg til omtaler, tilrettelegger GitHub referanseproblemer og pull-forespørsler Bare skriv inn # etterfulgt av et tall eller en del av tittelen. En liste med foreslåtte resultater vil vises, som du kan fylle ut på samme måte som med omtaler. Dette gjør navigasjonen mellom relaterte samtaler betraktelig raskere.

Hvis depotet ditt har konfigurert tilpassede autolenkede referanser, kan visse eksterne notasjoner (som JIRA- eller Zendesk-billett-ID-er) også automatisk konverteres til korte lenker. Denne innstillingen krever administratorrettigheter, men når den er aktivert, tillater den datadeling på tvers av systemer med minimal innsats.

Til slutt støtter GitHub emojier via kode: skriv inn et kolon, etterfulgt av emojinavnet, og avslutt med et nytt kolon. Når du begynner å skrive, vises en liste med forslag, som du kan godta med Tab eller Enter. Å innlemme emojier i kommentarene dine bidrar til å gi dem et mer menneskelig preg, så lenge du ikke overbruker dem i formell dokumentasjon.

Fotnoter og avansert innhold

GitHub støtter også Fotnoter Bruker en parentesbasert syntaks og en identifikator med et sammenflettet tegn. Der du vil ha referansen, setter du inn noe som , og på slutten av dokumentet definerer du teksten i notatet med samme tagg, etterfulgt av et kolon og innholdet.

Fotnoter kan strekke seg over flere linjer, og for å tvinge frem linjeskift i en fotnote brukes doble mellomrom på slutten av linjen, akkurat som i hoveddelen av Markdown. Ved gjengivelse viser GitHub en hevet skrift på teksten og en liste over fotnoter på slutten, med tilbakelenker for å navigere mellom referanser og fotnoter.

En annen avansert funksjon som GitHub tilbyr er... varsler Disse har allerede blitt diskutert (MERK, TIPS, VIKTIG, ADVARSEL og FORSIKTIG). Det anbefales å bare bruke dem når det er virkelig nødvendig, og å unngå å sette for mange sammen for å unngå å overvelde leseren. De kan ikke nestes i andre komplekse elementer, så nøye planlegging av plasseringen er viktig.

Til slutt kan du be GitHub om midlertidig å skjule deler av gjengitt Markdown ved å pakke dem inn i HTML-kommentarer, eller om å ignorere behandlingen av bestemte tegn med omvendte skråstreker. Dette er spesielt nyttig når du dokumenterer. Markdowns egen syntaks Og du må vise eksemplene slik de er, uten tolkning.

Markdown på Reddit: Snoomark og redigeringsmodus

Reddit er en diskusjonsplattform hvor nesten alle emner er velkomne, organisert i subreddits. Når det gjelder formatering, tilbyr den to editorer: en for rik tekst som er mer visuell, og en annen for ren tekst basert på Markdown. Hvis du vil jobbe raskt og ha god kontroll over resultatet, bør du bruke Markdown-alternativet.

Som standard aktiverer Reddit vanligvis riktekstredigereren, så for å bytte til markeringsmodus må du klikke på alternativet Markdown-modus i tekstboksen til et innlegg eller en kommentar. Derfra kan du bruke Snoomark-syntaksen direkte.

Hvis du foretrekker at Markdown-editoren alltid lastes inn, bør du gå til brukerinnstillinger, gå inn i Feedinnstillinger-delen og aktivere alternativet Standardinnstilling for nedsatt prisPå denne måten åpnes Markdown-redigeringsprogrammet automatisk hver gang du begynner å skrive et innlegg eller en kommentar, uten at du trenger å endre det manuelt.

Reddit støtter de fleste grunnleggende og avanserte Markdown-funksjonene: overskrifter, fet og kursiv skrift, lister, sitater, kodeblokker, lenker og noen av sine egne ekstrafunksjoner som spoilere. Imidlertid har den betydelige mangler sammenlignet med GitHub, spesielt i håndtering av bildersom avhenger ganske mye av konteksten og typen redaktør.

Syntaks støttet av Reddit og spoilere

Snoomark-varianten som brukes av Reddit inneholder mange elementer til felles med GitHub, så hvis du allerede er dyktig i Markdown for repositorier, er det ganske enkelt å overføre denne kunnskapen til Reddit-miljøet. Du kan bruke overskrifter til å strukturere lange innlegg, nummererte eller punktliste, sitater for å svare andre brukere og kodeblokker når du vil vise kommandoer eller tekniske utdrag.

En av de bemerkelsesverdige forskjellene er måten Reddit håndterer på bilderSelv om bilder i mange tilfeller lastes opp via det grafiske grensesnittet og ikke direkte med Markdown-syntaks, er motoren som behandler tekstinnholdet fortsatt Snoomark, så formateringen rundt disse bildene er basert på Markdown.

Reddit, derimot, legger til tilleggselementer som ikke er en del av standardspesifikasjonen, for eksempel spoilere. Disse lar deg skjule tekst bak et lag som brukeren kan avsløre med et klikk. Teknisk sett, når Reddit behandler en spoiler, transformeres den til en kombinasjon av HTML, CSS-klasser og plattformspesifikk JavaScript.

Den resulterende HTML-representasjonen av en spoiler inkluderer handlere som kontrollerer når innholdet skal vises eller skjules, og selv om noe lignende teoretisk sett kan skrives med ren HTML, avhenger det på Reddit av den interne implementeringen. Det viktige for deg som bruker er at når du skriver, trenger du bare å bruke den spesifikke spoiler-syntaksen som editoren tilbyr, og Snoomark har ansvaret for å oversette den til den aktuelle strukturen.

Kort sagt, Snoomark arver mange virkemåter fra GitHub Flavored Markdown, men rettet mot behovene til et diskusjonsfellesskap snarere enn prosjektdokumentasjon. Likevel forblir kjernen den samme: ren tekst med enkle symboler omgjort til strukturert og lesbart innhold.

Å mestre Markdown-syntaks på GitHub og Reddit gjør det mye mer effektivt å skrive teknisk dokumentasjon, åpne godt forklarte problemer, legge igjen tydelige kommentarer på pull-forespørsler og delta i Reddit-diskusjoner. Med noen få nøkkelregler – overskrifter, utheving, lister, sitater, kodeblokker, lenker, bilder og spesifikke triks som tabeller, sammenleggbare detaljer, varsler, fotnoter og spoilere – kan du gå fra å skrive ren tekst til å lage rent, skannbart og profesjonelt innhold uten å berøre en eneste museknapp.