Jak rychle používat Markdown na GitHubu a Redditu

Informatec Digital » Zdroje » Jak rychle používat Markdown na GitHubu a Redditu

Pokud pravidelně píšete na GitHubu nebo trávíte hodně času na Redditu, mastering Snížení ceny Je to jedna z těch věcí, které vám ušetří hodiny a usnadní život. Je to velmi lehký značkovací jazyk, který umožňuje rychle formátovat prostý text, aniž byste se museli potýkat s nabídkami nebo tlačítky, jen s několika symboly umístěnými na správná místa.

Na GitHubu to najdete všude: v souborech README.md z repozitářů, problémů, žádostí o změny, diskusí a dokonce i z vašeho vlastního profilu. Reddit používá variantu s názvem Snoomark (Markdown ve stylu Redditu), která dědí velkou část syntaxe GitHubu s některými jedinečnými funkcemi a určitými omezeními. Podívejme se krok za krokem a s mnoha příklady, Jak rychle používat Markdown na GitHubu a Redditu a aniž by se vynechalo cokoli důležitého.

Co je Markdown a proč je tak užitečný na GitHubu a Redditu?

Markdown je a lehký značkovací jazyk Navrženo tak, aby prostý text byl snadno čitelný a psaný a zároveň umožňovalo snadnou konverzi do formátu HTML. V praxi to znamená, že můžete psát běžný text a přidávat speciální znaky pro vytváření nadpisů, seznamů, tabulek, citací, formátovaného kódu, odkazů nebo obrázků.

Na GitHubu se jako implementace používá GitHub Flavored Markdown (GFM), která rozšiřuje klasickou syntaxi o tabulky, seznamy úkolů, pokročilé zvýrazňování kódu, podporu barev, upozornění a některé povolené HTML tagy. To vše se vykresluje automaticky v souborech .md a v polích komentářů platformy.

Reddit používá vlastní procesor s názvem Snoomark, derivát GFM. Sdílí většinu základního chování (tučné písmo, kurzíva, nadpisy, seznamy, citace, vložený nebo blokový kód, odkazy atd.), ale má… důležité vlastnostiNapříklad podpora obrázků je omezenější v závislosti na kontextu a přidává své vlastní prvky, jako jsou spoilery.

Krása toho všeho spočívá v tom, že s jedinou syntaxí můžete psát texty, které vypadají dobře jak na GitHubu, tak na Redditu, a upravovat jen pár detailů tam, kde každá platforma funguje jinak. Naučte se základní pravidla Umožňuje vám volně se pohybovat v obou, aniž byste se museli cokoli znovu učit od nuly.

Nadpisy a struktura obsahu

Jednou z prvních věcí, které použijete, je nadpisyJak na GitHubu, tak na Redditu se používají ke strukturování textu do sekcí a podsekcí.

V Markdownu se nadpis vytváří tak, že se před text vloží jeden až šest symbolů hash: jeden pro nadpis úrovně 1, dva pro úroveň 2 a tak dále až do úrovně 6. Například v souboru README.md z GitHubu může být něco jako: # Hlavní název, ## Sekce, ### Podsekce, Etc.

Když GitHub najde v souboru dvě nebo více hlaviček, automaticky vygeneruje obsah Přístupné z ikony „Osnova“ v horní části souboru. Každý nadpis se zobrazí jako odkaz, který vás přesměruje přímo do dané sekce, což je skvělé pro dlouhé dokumenty.

Kromě toho se každý nadpis stává interní kotvou, na kterou můžete odkazovat pomocí úryvku URL na základě textu nadpisu. Pro generování tohoto úryvku GitHub používá velmi specifická pravidla: převádí písmena na malá písmena, nahrazuje mezery pomlčkami, odstraňuje interpunkční znaménka a formátovací znaky (například kurzívu), ořezává přebytečné mezery a pokud se výsledek shoduje s jiným předchozím nadpisem, přidat číselnou příponu (-1, -2 atd.), aby byl jedinečný.

To vám umožňuje dělat věci, jako je umístění sekce ## Ukázková sekce a pak na něj odkázat z jiného místa v dokumentu pomocí odkazu, jako je tento: (#ukázková-sekce)nebo dokonce odkazovat na sekce se speciálními znaky v názvu, protože GitHub generuje úryvek podle těchto pravidel a zpřístupňuje ho se stejným vzorem.

Důraz, zvýrazněný text a citace

Markdown umožňuje zvýrazňovat text pomocí různých metod důrazTučné písmo, kurzíva, přeškrtnuté písmo, dolní index, horní index nebo podtržené písmo. Na GitHubu by typická tabulka stylů vypadala nějak takto, i když jsme ji zde shrnuli jinými slovy:

Vložení textu tučněTučný text se uzavírá do dvojitých hvězdičky nebo dvojitého podtržítka; pro kurzívu se používají jednoduché hvězdičky nebo podtržítka; pro přeškrtnutí se na obě strany textu umístí dvojitá vlnovka (dvě vlnovky). Vnořené tučné písmo a kurzívu lze také kombinovat, tři hvězdičky lze použít k aplikaci obou na celou část textu nebo lze použít HTML tagy, například <br>. _{y ^{pro dolní a horní indexy a pro podtržení.}}

GitHub vám také umožňuje vytvářet citace ve stylu blokových citátů Umístěním symbolu větší než (>) na začátek řádku se citovaný text zobrazí se svislou čárou vlevo a šedě, čímž se jasně odliší. Do stejného bloku citací lze zahrnout více řádků a citace lze dokonce vnořovat přidáním dalších symbolů > na začátek.

Pokročilá forma citace, která existuje pouze na GitHubu, je upozornění nebo napomenutíJsou založeny na stejné syntaxi blokových citací, ale první řádek obsahuje speciální značku pro označení typu upozornění. Můžete například zadat `<alert>` pro užitečné informace, `<helpful tips>` pro praktické rady, `<key data>` pro klíčová data, `<urgent notices>` pro naléhavá varování a `<alert>` pro varování před riziky nebo negativními důsledky. GitHub zobrazuje každý typ jinou barvou a ikonou, což pomáhá zvýraznit důležité informace v dokumentaci.

Reddit také podporuje jednoduché uvozovky se stejným symbolem >, ačkoliv postrádá bohatý systém upozornění GitHubu. I tak je to stále velmi užitečný způsob, jak odpovědět někomu citací části jeho zprávy aniž by se to úplně opakovalo.

Zvýrazňování kódu, bloky a barvy

GitHub i Reddit umožňují zvýrazňovat úryvky kódu v textu pomocí zpětných attachů. U inline kódu uzavřete slovo nebo příkaz jedním zpětným attachem na každé straně. To je ideální například pro zvýraznění git status ve větě, čímž je jasné, že se jedná o příkaz.

Pokud chcete samostatný blok kódu, Markdown používá tři zpětné anotace: napíšete řádek se třemi zpětnými anotacemi, poté kód na samostatných řádcích a uzavřete dalšími třemi zpětnými anotacemi. Na GitHubu, pokud hned za první zpětnou anotací zadáte i jazyk, platí... zvýraznění syntaxe s barvami a formátem specifickými pro daný jazyk.

GitHub také nabízí specifickou funkci pro zvýrazňování barevné hodnoty uvnitř zpětných anotací. Pokud mezi zpětné anotace zadáte barvu v hexadecimálním, RGB nebo HSL formátu, platforma zobrazí vedle textu malý indikátor barvy. Pokud je například barva pozadí ve světlém režimu #ffffff a v tmavém režimu #000000, zvýraznění těchto kódů vám umožní rychle zjistit, která je která.

Pokud jde o vizualizaci kódu a tabulek, GitHub umožňuje povolit fixní písmo s monospace ve všech polích pro komentáře, což usnadňuje práci s technickým textem. Pokud upravujete mnoho úryvků kódu v prohlížeči nebo v editorech, jako je Kód Visual StudioPovolení této možnosti usnadňuje zarovnání a čtení. mnohem soudržnější.

Reddit také podporuje bloky kódu se zpětnými attachmenty, a to jak inline, tak i blokové, ačkoli jejich použití je zde zaměřeno spíše na malé úryvky nebo pseudokód než na dlouhou dokumentaci, jako je ta v repozitáři.

Odkazy, kotvy a interní navigace

Vytváření odkazů v Markdownu je velmi jednoduché: text, který se má uživateli zobrazit, uzavřete do hranatých závorek a URL adresu do kulatých závorek. Toto funguje na GitHubu i Redditu a lze to vylepšit klávesovými zkratkami na GitHubu (například pomocí klávesových zkratek pro rychlý převod vybraného textu na odkaz).

GitHub přidává některé další funkce související s navigací. V prvé řadě umožňuje odkazovat přímo na nadpisy s využitím dříve popsaných pravidel generování fragmentů. Navíc podporuje relativní odkazy v rámci samotného repozitáře, což je klíčové pro technickou dokumentaci.

Relativní odkaz je odkaz, který se vypočítává s použitím aktuálního souboru jako reference. Pokud se například váš soubor README nachází v kořenovém adresáři projektu a chcete odkazovat na soubor docs/CONTRIBUTING.md, jednoduše napíšete odkaz s cestou docs/CONTRIBUTING.md. GitHub se postará o správný překlad tohoto relativního odkazu v jakékoli větvi, na které se nacházíte, a zabrání tak jeho přerušení při přepínání větví nebo klonování repozitáře.

Doporučení je vždy používat relativní cesty Pro navigaci mezi soubory v rámci stejného repozitáře, protože absolutní odkazy mohou v klonech nebo forcích přestat fungovat, umožňuje GitHub použití standardních operátorů, jako jsou ./ nebo ../, a cest začínajících na / vzhledem ke kořeni projektu.

Pokud chcete v dokumentu vytvořit vlastní kotevní body mimo nadpisy, můžete použít HTML tagy s atributem `name`. To vám umožní umístit cílový bod doprostřed odstavce nebo vedle textu, který nemá vlastní nadpis, a odkazovat na něj pomocí stejné syntaxe jako u automaticky generovaných nadpisů.

Obrázky na GitHubu: Markdown, HTML a relativní cesty

Na GitHubu se obrázky obvykle vkládají pomocí stejné syntaxe jako odkazy, ale s předchůdcem v podobě vykřičníku. Alternativní text (alt) je uveden v hranatých závorkách a URL adresa nebo cesta k obrázku je umístěna v kulatých závorkách. Tento alternativní text je důležitý pro… přístupnostprotože to je to, co čtečky obrazovky přečtou a co se zobrazí, pokud se obrázek nenačte.

Obrázky mohou pocházet ze souborů v samotném repozitáři nebo z externích URL adres. GitHub umožňuje více vzorů relativních cest pro nahrávání obrázků z různých větví, jiných repozitářů nebo dokonce problémů a komentářů pomocí přípon, jako například ?raw=true v případě potřeby vynutit přímé stažení souboru.

Kromě standardní syntaxe Markdownu podporuje GitHub použití elementu HTML. Tato položka je obzvláště užitečná pro nabíjení responzivní obrázky Ty se mění podle uživatelových preferencí motivu (světlý nebo tmavý). Pomocí mediálního dotazu `prefers-color-scheme` můžete definovat různé zdroje obrázků pro každý režim a výchozí obrázek pro prohlížeče, které tuto funkci nepodporují.

Typický vzorec zahrnuje zahrnutí několik prvků s atributy media a srcset a nakonec a Pomocí atributu alt a generické adresy URL uvidí uživatelé v tmavém režimu upravený obrázek, zatímco uživatelé ve světlém režimu obdrží jiný, aniž by museli duplikovat obsah souboru README.

GitHub také podporuje HTML komentáře v souborech Markdown, což umožňuje přidávat čtenáři neviditelné připomínky, například k aktualizaci sekce s obrázkem nebo k pozdějšímu přidání nových příkladů.

Tabulky, rozkládací sekce a oddělení obsahu

Jedním z nejužitečnějších vylepšení GitHub Flavored Markdown je podpora pro tabulkyData můžete uspořádat do řádků a sloupců pomocí svislých pruhů k oddělení buněk a přerušované čáry k označení záhlaví. Sloupce můžete také zarovnat doprava, doleva nebo na střed pomocí dvojtečky v oddělovacím řádku.

Tabulky jsou velmi užitečné pro prezentaci seznamů programovacích jazyků, použitých frameworků, plánovaných úkolů, porovnání funkcí nebo jakýchkoli jiných informací, které prospívají maticové struktuře. GitHub tyto tabulky vykresluje v čistém a čitelném stylu.

Pro uspořádání dlouhého souboru README můžete použít značku HTML vytvořit sbalitelné sekce. Tyto sekce zobrazují souhrn uvnitř popisku a umožnit uživateli rozšířit nebo zmenšit další obsah podle potřeby. Je běžné uzavírat tabulky nebo bloky sekundárních informací dovnitř aby se zabránilo zahlcení očí.

Pokud chcete, aby se sekce ve výchozím nastavení zobrazovala rozbalená, jednoduše přidejte atribut open k Tato technika je velmi praktická pro seskupování žebříčků, dlouhých seznamů nebo obsahu, který není nezbytný pro první čtení, ale je vhodné ho mít snadno dostupný.

Dalším jednoduchým nástrojem pro organizaci informací je horizontální pravidlo. Vytvoří se napsáním tří nebo více čárek na čáru a slouží k nakreslení dělicí čáry mezi sekcemi, což umožňuje jasně oddělit například popisnou část od sekce s odkazy nebo doplňujícími poznámkami.

Tato pravidla lze kombinovat s citacemi na konci dokumentu pro zvýraznění inspirativních frází, připomínek nebo klíčových sdělení. Typickým příkladem by bylo umístění motivačního citátu na konec souboru README vašeho profilu, formátovaného s blokovou citací za oddělovací čárou.

Skryté komentáře a ovládání formátu

GitHub vám umožňuje představit HTML komentáře v Markdownu s využitím syntaxe Cokoli vložíte do tohoto komentáře, se nezobrazí ve vykresleném obsahu, ale bude to viditelné ve zdrojovém kódu, takže je to ideální pro interní poznámky nebo úkoly.

Například v souboru README profilu můžete přidat komentář, který říká něco jako „potřebujete později rozbalit sekci „O mně““ nebo „potřebujete zkontrolovat tabulku zastaralých technologií“, aniž by ji kdokoli, kdo profil přímo navštívil, viděl.

Další užitečnou funkcí je escape znaky což by se normálně interpretovalo jako Markdown. Pokud potřebujete zobrazit hvězdičky, křížky nebo jiné symboly doslova, aniž by byly formátovány, jednoduše před každý z nich umístěte zpětné lomítko. To vám například umožní psát výrazy, které obsahují symboly seznamů, aniž byste je převáděli na skutečné seznamy.

Když si na GitHubu prohlížíte soubor s kódem, máte možnost přepínat mezi vykresleným zobrazením a zdrojovým kódem pomocí tlačítka v horní části (nebo jej otevřít v editorech, jako je KonzolyZakázání interpretace Markdownu vám umožní přístup k typickým funkcím zobrazení kódu, jako například propojit konkrétní řádkyTo je velmi užitečné, když chcete odkazovat na přesnou část souboru README nebo libovolného souboru .md.

Nakonec nezapomeňte, že GitHub zpracovává zalomení řádků odlišně v komentářích (problémy, PR atd.) a v souborech .md. V komentářích jsou zalomení řádků respektována přímo, zatímco v souborech Markdown je třeba na konec řádku přidat dvě mezery, zpětné lomítko nebo tečku. vynutit skok v rámci stejného odstavce.

Seznamy, vnořené seznamy a seznamy úkolů

Seznamy jsou jedním z nejpoužívanějších prvků v Markdownu, a to jak na GitHubu, tak na Redditu. Seznamy si můžete vytvářet. neuspořádaný umístěním pomlčky, hvězdičky nebo znaménka plus před každou položku seznamu. Všechny tyto značky se vykreslují podobně jako odrážky.

Generování seznamů objednalKaždý řádek je očíslován číslem, za nímž následuje tečka a mezera. Pořadí čísel sice nemusí být dokonalé (GitHub ho obvykle přepočítává), ale je vhodné zachovat konzistentní číslování, aby byl zdrojový kód čitelný.

Vnořené seznamy se vytvářejí jednoduše přidáním odsazení k položkám pod nimi. V editorech s pevnou šířkou, jako je Sublime TextJednoduše zarovnejte vnořené značky seznamu vizuálně pod první znak textu v nadřazeném elementu. V kontextech, jako je editor komentářů GitHub, kde písmo není neproporcionální, spočítejte počet znaků před textem a tento počet mezer použijte pro odsazení.

Můžete také vytvořit více úrovní vnoření, pokud zachováte konzistenci v počtu mezer. U velmi složitých seznamů vyžaduje tento systém trochu cviku, ale jakmile si ho osvojíte, je jeho aplikace velmi rychlá.

GitHub také nabízí seznamy úkolůTyto seznamy jsou velmi užitečné pro úkoly, žádosti o změny a dokumentaci. Vytvářejí se tak, že se před nimi napíše pomlčka, mezera a hranaté závorky s mezerou nebo křížkem uvnitř: pro čekající úkoly a pro dokončené úkoly. Tyto seznamy se vykreslují pomocí zaškrtávacích políček, která lze v rozhraní zaškrtnout nebo zrušit zaškrtnutí.

Pokud text položky seznamu úkolů začíná závorkami, musí být ukončen zpětným lomítkem, aby se zabránilo nejasnostem v analyzátoru. Je to malý detail, ale důležitý při psaní popisů, které začínají něčím jako „(Volitelné)“ nebo podobně.

Zmínky, reference a emoji na GitHubu

Jednou z výhod psaní v Markdownu na GitHubu je možnost používat zmiňuje se Přímé zprávy uživatelům a týmům na platformě. Jednoduše napište @ a poté uživatelské jméno nebo název týmu a GitHub pošle na daný účet oznámení, které upoutá jejich pozornost na konverzaci.

Když zadáte symbol @, GitHub zobrazí seznam uživatelů a týmů přidružených k repozitáři nebo vláknu a tento seznam můžete během psaní filtrovat. Pomocí kláves se šipkami a stisknutím klávesy Enter nebo Tab přijměte návrhy. Pro týmy použijte formát @organizace/název-týmu a všichni členové týmu budou přihlášeni k odběru vlákna.

Kromě zmínek GitHub usnadňuje problémy s referencemi a pull requesty Jednoduše napište # a za ním číslo nebo část názvu. Zobrazí se seznam navrhovaných výsledků, který můžete vyplnit stejným způsobem jako u zmínek. To výrazně urychlí navigaci mezi souvisejícími konverzacemi.

Pokud má váš repozitář nakonfigurované vlastní automaticky propojené reference, mohou být některé externí notace (například ID tiketů JIRA nebo Zendesk) také automaticky převedeny na krátké odkazy. Toto nastavení vyžaduje administrátorská oprávnění, ale po povolení umožňuje sdílení dat mezi systémy s minimálním úsilím.

GitHub konečně podporuje emoji prostřednictvím kódu: napište dvojtečku, následovanou názvem emoji a zakončete další dvojtečkou. Jakmile začnete psát, zobrazí se seznam návrhů, které můžete přijmout stisknutím klávesy Tab nebo Enter. Začlenění emoji do komentářů jim pomáhá dodat lidštější nádech, pokud je ve formální dokumentaci nepřeháníte.

Poznámky pod čarou a pokročilý obsah

GitHub také podporuje Poznámky pod čarou Použití syntaxe založené na závorkách a identifikátoru s prokládaným znakem. Na místo, kam chcete odkaz, vložíte něco jako a na konec dokumentu definujete text dané poznámky se stejnou značkou, následovaný dvojtečkou a obsahem.

Poznámky pod čarou mohou zabírat více řádků a pro vynucení zalomení řádků v rámci poznámky pod čarou se na konci řádku používají dvojité mezery, stejně jako v hlavní části Markdownu. Při vykreslování GitHub zobrazuje horní index textu a na konci seznam poznámek pod čarou se zpětnými odkazy pro navigaci mezi odkazy a poznámkami pod čarou.

Další pokročilou funkcí, kterou GitHub nabízí, je... alertas Tyto již byly probrány (POZNÁMKA, TIP, DŮLEŽITÉ, VAROVÁNÍ a POZOR). Je vhodné je používat pouze v nezbytných případech a vyhnout se jejich přílišnému řazení, aby se čtenář nezahltil. Nelze je vnořovat do jiných složitých prvků, proto je nezbytné pečlivé plánování jejich umístění.

Nakonec můžete požádat GitHub, aby dočasně skryl části vykresleného Markdownu jejich zabalením do HTML komentářů, nebo aby ignoroval zpracování určitých znaků pomocí zpětných lomítek. To je obzvláště užitečné při dokumentaci. Vlastní syntaxe Markdownu A je potřeba ukázat příklady takové, jaké jsou, bez interpretace.

Markdown na Redditu: Snoomark a režim úprav

Reddit je diskusní platforma, kde je vítáno téměř jakékoli téma, organizované do subredditů. Co se týče formátování, nabízí dva editory: jeden pro vizuální formátovaný text a druhý pro prostý text založený na Markdownu. Pokud chcete pracovat rychle a mít přesnou kontrolu nad výsledkem, budete chtít použít možnost Markdown.

Ve výchozím nastavení Reddit obvykle aktivuje editor formátovaného textu, takže pro přepnutí do režimu značek musíte kliknout na tuto možnost. Režim Markdown v textovém poli příspěvku nebo komentáře. Odtud můžete přímo použít syntaxi Snoomarku.

Pokud chcete, aby se editor Markdownu načítal vždy, měli byste přejít do nastavení uživatele, vstoupit do sekce Nastavení kanálu a aktivovat příslušnou možnost. Výchozí nastavení pro MarkdownTímto způsobem se pokaždé, když začnete psát příspěvek nebo komentář, editor Markdown se automaticky otevře, aniž byste ho museli ručně měnit.

Reddit podporuje většinu základních i pokročilých funkcí Markdownu: nadpisy, tučné písmo a kurzívu, seznamy, citace, bloky kódu, odkazy a některé vlastní doplňky, jako jsou spoilery. Ve srovnání s GitHubem má však značné nedostatky, zejména v… manipulace s obrázkycož dost záleží na kontextu a typu editora.

Syntaxe podporovaná Redditem a spoilery

Varianta Snoomarku používaná Redditem obsahuje mnoho společných prvků s GitHubem, takže pokud již ovládáte Markdown pro repozitáře, přenos těchto znalostí do prostředí Redditu je poměrně jednoduchý. Nadpisy můžete použít ke strukturování dlouhých příspěvků, číslované nebo odrážkové seznamy, citace k odpovědi ostatním uživatelům a bloky kódu, když chcete zobrazit příkazy nebo technické úryvky.

Jedním z pozoruhodných rozdílů je způsob, jakým Reddit nakládá s... obraznostAčkoli se v mnoha případech obrázky nahrávají přes grafické rozhraní a ne přímo se syntaxí Markdown, engine, který zpracovává textový obsah, je stále Snoomark, takže formátování kolem těchto obrázků je založeno na Markdownu.

Reddit na druhou stranu dodává doplňkové prvky které nejsou součástí standardní specifikace, například spoilery. Ty umožňují skrýt text za vrstvou, kterou může uživatel odhalit kliknutím. Technicky vzato, když Reddit zpracovává spoiler, transformuje ho do kombinace HTML, CSS tříd a JavaScriptu specifického pro danou platformu.

Výsledná HTML reprezentace spoileru obsahuje obslužné rutiny, které řídí, kdy se má obsah zobrazit nebo skrýt, a ačkoli teoreticky by se něco podobného dalo napsat i v prostém HTML, na Redditu to závisí na jeho interní implementaci. Důležité pro vás jako uživatele je, že při psaní stačí použít pouze specifickou syntaxi spoileru poskytovanou editorem a Snoomark má na starosti překlad k příslušné struktuře.

Stručně řečeno, Snoomark dědí mnoho chování z GitHub Flavored Markdown, ale je zaměřen spíše na potřeby diskusní komunity než na projektovou dokumentaci. Jádro však zůstává stejné: prostý text s jednoduchými symboly transformovaný do strukturovaného a čitelného obsahu.

Zvládnutí syntaxe Markdownu na GitHubu a Redditu výrazně zefektivňuje psaní technické dokumentace, otevírání dobře vysvětlených problémů, zanechávání jasných komentářů k žádostem o změny a účast v diskusích na Redditu. S několika klíčovými pravidly – ​​nadpisy, zdůraznění, seznamy, citace, bloky kódu, odkazy, obrázky a specifické triky, jako jsou tabulky, sbalitelné detaily, upozornění, poznámky pod čarou a spoilery – můžete přejít od psaní prostého textu k vytváření... čistý, čitelný a profesionální obsah bez dotyku jediného tlačítka myši.