Как бързо да използвате Markdown в GitHub и Reddit

Информатек Дигитал » Ресурси » Как бързо да използвате Markdown в GitHub и Reddit

Ако често пишете в GitHub или прекарвате много време в Reddit, овладяването на Markdown е едно от онези неща, които ви спестяват часове и улесняват живота ви. Това е много лек език за маркиране, който ви позволява бързо да форматирате обикновен текст, без да се затруднявате с менюта или бутони, само с няколко символа, поставени на правилните места.

В GitHub ще го намерите навсякъде: във файловете README.md на хранилището , задачи, заявки за изтегляне, дискусии и дори във вашия собствен профил. Reddit, от друга страна, използва вариант, наречен Snoomark (Markdown в стил Reddit), който наследява голяма част от синтаксиса на GitHub, с някои уникални функции и ограничения. Нека видим, стъпка по стъпка и с много примери, как да използвате Markdown в GitHub и Reddit бързо и без да пропуснете нищо важно.

Какво е Markdown и защо е толкова полезен в GitHub и Reddit?

Markdown е лек език за маркиране , предназначен да направи обикновения текст лесен за четене и писане, като същевременно позволява лесно преобразуване в HTML. На практика това означава, че можете да пишете нормален текст и да добавяте няколко специални знака, за да създавате заглавия, списъци, таблици, цитати, форматиран код, връзки или изображения.

В GitHub използваната имплементация е GitHub Flavored Markdown (GFM), която разширява класическия синтаксис с таблици, списъци със задачи, разширено маркиране на код, поддръжка на цветове, предупреждения и някои разрешени HTML тагове. Всичко това се рендира автоматично в .md файлове и в полетата за коментари на платформата.

Reddit използва собствен редактор, наречен Snoomark, производен на GFM. Той споделя голяма част от основното поведение (удебелен шрифт, курсив, заглавия, списъци, цитати, вграден или блоков код, връзки и др.), но има важни особености : например, поддръжката на изображения е по-ограничена в зависимост от контекста и добавя свои собствени елементи, като например спойлери.

Хубавото на всичко това е, че с един-единствен синтаксис можете да пишете текстове, които изглеждат добре както в GitHub, така и в Reddit, адаптирайки само няколко детайла, където всяка платформа работи различно. Изучаването на основните правила ви позволява да се ориентирате и в двете с лекота, без да се налага да учите нещо от нулата.

Заглавия и структура на съдържанието

Едно от първите неща, които ще използвате, са заглавията , както в GitHub, така и в Reddit. Те помагат за структурирането на текста в секции и подраздели.

В Markdown заглавието се създава, като пред текста се поставят от един до шест символа „диез“: един за заглавие от ниво 1, два за ниво 2 и така нататък до ниво 6. Например, във файл README.md на GitHub може да имате нещо като: # ОсновноЗаглавие , ##Раздел , ### Подраздел и т.н.

Когато GitHub намери две или повече заглавия във файл, той автоматично генерира съдържание, достъпно от иконата „Структура“ в горната част на файла. Всяко заглавие се показва като връзка, която ви отвежда директно до съответния раздел, което е чудесно за дълги документи.

Освен това, всяко заглавие се превръща в вътрешна котва, към която можете да се свържете с URL фрагмент, базиран на текста на заглавието. За да генерира този фрагмент, GitHub прилага много специфични правила: преобразува буквите в малки, замества интервалите с тирета, премахва препинателните и форматиращите знаци (като курсив), отрязва излишните интервали и, ако резултатът съвпада с друго предишно заглавие, добавя числов суфикс (-1, -2 и т.н.), за да го направи уникален.

Това ви позволява да правите неща като поставяне на ## Примерен раздел и след това да се свържете с него от друга точка в документа с връзка като (#примерен-раздел) или дори да се свържете с раздели със специални символи в заглавието, тъй като GitHub генерира фрагмента, следвайки тези правила, и го прави достъпен със същия шаблон.

Акцент, подчертан текст и цитати

Markdown ви позволява да маркирате текст, използвайки различни форми на акцентиране : удебелен шрифт, курсив, зачеркнат шрифт, долен индекс, горен индекс или подчертаване. В GitHub типичната таблица със стилове би изглеждала по следния начин, въпреки че тук сме я обобщили с различни термини:

За да направите текста удебелен , оградете го с двойни звездички или двойни долни черти; за курсив използвайте единични звездички или долни черти; за зачеркване използвайте двойна тилда (две тилди) от двете страни на текста. Можете също да комбинирате вложени удебелен и курсивен шрифт, да използвате три звездички, за да приложите и двете към цял раздел от текста, или да използвате HTML тагове като `<b>` _{за ^{долни и горни индекси и `<i>` за подчертавания.}}

GitHub ви позволява също да създавате блокови цитати, като поставите символа „по-голямо от“ (>) в началото на реда. Цитираният текст се показва с вертикална лента отляво и в сиво, което го прави ясно видим. Можете да имате няколко реда в един и същ блоков цитат и дори да влагате цитати, като добавите още символи „>“ в началото.

Усъвършенствана форма на цитиране, уникална за GitHub, е предупреждението или предупреждението . То използва същия синтаксис за блокови цитати, но първият ред включва специален маркер, който обозначава типа на предупреждението. Например, можете да укажете „предупреждение“ за полезна информация, „полезни съвети“, „ключови данни“, „спешни предупреждения“ и „предупреждения за рискове или отрицателни последици“. GitHub показва всеки тип с различен цвят и икона, което помага да се открои критична информация във вашата документация.

Reddit също поддържа прости цитати със същия символ >, въпреки че му липсва богатата система за ping на GitHub. Въпреки това, той остава много полезен начин да отговорите на някого, като цитирате част от съобщението му, без да го повтаряте изцяло.

Маркиране на код, блокове и цветове

Както GitHub, така и Reddit ви позволяват да маркирате фрагменти от код в текста, използвайки обратни бележки. За вграден код, ограждате думата или командата с по една обратна бележка от всяка страна. Това е идеално за маркиране например на „ git status“ в изречение, за да стане ясно, че това е команда.

Когато искате самостоятелен блок код, Markdown използва три обратни забележки: пишете ред с три обратни забележки, след това кода на отделни редове и завършвате с още три обратни забележки. В GitHub, ако укажете и езика веднага след първите обратни забележки, се прилага синтактично оцветяване с цветове и форматиране, специфични за този език.

GitHub предлага и специфична функция за подчертаване на стойностите на цветовете в рамките на обратните бележки. Ако въведете цвят в шестнадесетичен, RGB или HSL формат между обратните бележки, платформата включва малък индикатор за цвят до текста. Например, ако цветът на фона в светъл режим е #ffffff, а в тъмен режим е #000000, подчертаването на тези кодове ви позволява бързо да видите кой е кой.

Що се отнася до показването на код и таблици, GitHub ви позволява да активирате фиксиран моноширочен шрифт във всички полета за коментари, което улеснява работата с технически текст. Ако редактирате много фрагменти от код в браузъра си или в редактори като Visual Studio Code , активирането на тази опция прави подравняването и четливостта много по-последователни.

Reddit също поддържа кодови блокове с обратни бележки, както инлайн, така и блокови, въпреки че използването им там е фокусирано повече върху малки фрагменти или псевдокод, отколкото върху дълга документация, като тази на хранилище.

Връзки, котви и вътрешна навигация

Създаването на връзки в Markdown е много лесно: ограждате текста, който ще се показва на потребителя, в квадратни скоби, а URL адреса – в скоби. Това работи както в GitHub, така и в Reddit и може да се подобри с клавишни комбинации в GitHub (например, използване на клавишни комбинации за бързо преобразуване на избрания текст във връзка).

GitHub добавя някои допълнителни функции, свързани с навигацията. Първо, той ви позволява да се свързвате директно със заглавия, използвайки правилата за генериране на фрагменти, обсъдени по-рано. Второ, поддържа относителни връзки в самото хранилище, което е от решаващо значение за техническата документация.

Относителната връзка е тази, която се изчислява, използвайки текущия файл като референция. Например, ако вашият README файл е в корена на проекта и искате да го свържете към файл docs/CONTRIBUTING.md, просто пишете връзка с пътя docs/CONTRIBUTING.md. GitHub се грижи за правилното превеждане на тази относителна връзка във всеки клон, в който се намирате, предотвратявайки нейното прекъсване при превключване между клонове или клониране на хранилището.

Препоръката е винаги да използвате относителни пътища, когато навигирате между файлове в едно и също хранилище, защото абсолютните връзки може да спрат да работят в клонинги или форкове. GitHub позволява използването на стандартни оператори като ./ или ../ и пътища, които започват с / спрямо корена на проекта.

Ако искате да създадете персонализирани точки за закрепване в документа извън заглавията, можете да използвате HTML тагове с атрибута `name`. Това ви позволява да поставите целева точка в средата на параграф или до текст, който няма собствено заглавие, и да се свържете с нея, използвайки същия синтаксис, както за автоматично генерирани заглавия.

Изображения в GitHub: Markdown, HTML и относителни пътища

В GitHub изображенията обикновено се вграждат, използвайки същия синтаксис като връзките, но предшествани от удивителен знак. Алтернативният текст (alt) се посочва в квадратни скоби, а URL адресът или пътят до изображението се поставя в скоби. Този алтернативен текст е важен за достъпността , тъй като е това, което екранните четци ще прочетат и какво ще се покаже, ако изображението не се зареди.

Изображенията могат да идват от файлове в самото хранилище или от външни URL адреси. GitHub позволява множество модели на относителни пътища за качване на изображения от различни клонове, други хранилища или дори проблеми и коментари, използвайки суфикси като ?raw=true, за да се наложи директно изтегляне на файла, когато е необходимо.

В допълнение към стандартния синтаксис на Markdown, GitHub поддържа използването на HTML елемента `<picture>`. Този елемент е особено полезен за зареждане на адаптивни изображения , които се променят според предпочитанията за тема на потребителя (светла или тъмна). Използвайки медийната заявка `prefers-color-scheme`, можете да дефинирате различни източници на изображения за всеки режим и изображение по подразбиране за браузъри, които не поддържат тази функция.

Типичният модел включва включване в няколко елемента с атрибутите си media и srcset и накрая a Използвайки атрибута alt и генеричен URL адрес, потребителите в тъмен режим виждат адаптирано изображение, докато тези в светъл режим получават различно, без да е необходимо да дублират съдържанието във файла README.

GitHub също така поддържа HTML коментари в Markdown файлове, което ви позволява да добавяте невидими напомняния за читателя, например, за да му напомните да актуализира раздел с изображение или да добави нови примери по-късно.

Таблици, разгъващи се секции и разделяне на съдържанието

Едно от най-полезните подобрения в GitHub Flavored Markdown е поддръжката на таблици . Можете да организирате данните в редове и колони, като използвате вертикални ленти за разделяне на клетките и ред тирета за маркиране на заглавката. Възможно е също така да подравните колоните надясно, наляво или центрирано, като използвате двоеточие в разделителния ред.

Таблиците са много полезни за представяне на списъци с езици за програмиране, използвани рамки, планирани задачи, сравнения на функции или всяка друга информация, която се възползва от матрична структура. GitHub рендира тези таблици с изчистен и четим стил.

За да поддържате дългия README файл организиран, можете да използвате HTML етикета `<details>`, за да създадете свиваеми секции. Тези секции показват обобщение в етикета `<summary>` и позволяват на потребителя да разгъва или свива допълнително съдържание, ако е необходимо. Обичайна практика е да се ограждат таблици или блокове с вторична информация в `<details>`, за да се избегне претоварването на потребителя от пръв поглед.

Ако искате секцията да се показва разгъната по подразбиране, просто добавете атрибута open към Тази техника е много практична за групиране на класации, дълги списъци или съдържание, което не е от съществено значение за първо четене, но е удобно да се поддържа достъпно.

Друг прост инструмент за организиране на информация е хоризонталното правило. То се създава чрез написване на три или повече тирета на линия и служи за начертаване на разделителна линия между раздели, което ви позволява ясно да отделите например описателен раздел от раздел с препратки или допълнителни бележки.

Тези правила могат да се комбинират с цитати в края на документа, за да се подчертаят вдъхновяващи фрази, напомняния или ключови послания. Типичен пример би било поставянето на мотивационен цитат в края на README файла на вашия профил, форматиран с блоков цитат след разделителна линия.

Скрити коментари и контрол на формата

GitHub ви позволява да вмъквате HTML коментари в Markdown, използвайки синтаксиса <!-- comment -->. Всичко, което поставите в този коментар, няма да се показва в рендираното съдържание, но ще бъде видимо в изходния код, което го прави идеален за вътрешни бележки или задачи.

Например, в README файла на профила можете да добавите коментар, който гласи нещо от рода на „трябва да разширите секцията „За мен“ по-късно“ или че трябва да прегледате таблица с остарели технологии, без никой, посещаващ профила, да я вижда директно.

Друга полезна функция е екранирането на символи , които обикновено биха се интерпретирали като Markdown. Ако трябва да покажете звездички, символи за диез или други символи буквално, без да бъдат форматирани, просто поставете обратна наклонена черта пред всеки от тях. Това ви позволява например да пишете изрази, които включват символи за списъци, без да ги преобразувате в действителни списъци.

Когато преглеждате файл с маркиране в GitHub, имате възможност да превключвате между рендерирания изглед и изходния код с бутон в горната част (или да го отворите в редактори като Brackets ). Деактивирането на интерпретацията на Markdown ви дава достъп до типични функции за преглед на код, като например свързване на конкретни редове , което е много полезно, когато искате да маркирате точен раздел от README или друг .md файл.

Накрая, не забравяйте, че GitHub обработва разделянето на редове по различен начин в коментарите (проблеми, PR и др.) и в .md файловете. В коментарите разделянето на редове се спазва директно, докато в Markdown файловете трябва да добавите два интервала в края на реда, обратна наклонена черта или точка. за да се осъществи преход в рамките на същия параграф.

Списъци, вложени списъци и списъци със задачи

Списъците са едни от най-често използваните елементи в Markdown, както в GitHub, така и в Reddit. Можете да създавате неподредени списъци , като пред всеки елемент от списъка поставите тире, звездичка или знак плюс. Всички тези маркери се изобразяват подобно на точките.

За да генерирате подредени списъци , номерирайте всеки ред с число, последвано от точка и интервал. Макар че редът на числата не е задължително да е перфектен (GitHub обикновено го преизчислява), добра идея е да поддържате последователно номериране, за да запазите четливостта на изходния код.

Вложените списъци се създават просто чрез отстъпване на елементите под тях. В редактори с моноширинен шрифт като Sublime Text , просто трябва визуално да подравните маркерите на вложените списъци под първия символ на текста в родителския елемент. В контексти като редактора на коментари на GitHub, където шрифтът не е моноширинен, трябва да преброите колко символа са преди текста и да използвате този брой интервали за отстъпване.

Можете също така да изградите няколко нива на влагане, стига да поддържате последователност в броя на интервалите. За много сложни списъци тази система изисква малко практика, но след като я свикнете, е много бърза за прилагане.

GitHub предлага и списъци със задачи , които са много полезни за проблеми, заявки за изтегляне и документация. Те се създават, като пред списъка се постави тире, интервал и чифт квадратни скоби с интервал или "x" вътре: една за чакащи задачи и една за завършени задачи. Тези списъци се изобразяват с квадратчета за отметка, които могат да бъдат избрани или отменени от интерфейса.

Ако текстът на елемент от списъка със задачи започва със скоби, той трябва да бъде екраниран с обратна наклонена черта, за да се избегне объркване в парсера. Това е малък детайл, но е важен, когато се пишат описания, които започват с нещо като „(Незадължително)“ или подобно.

Споменавания, препратки и емоджита в GitHub

Едно от предимствата на писането в Markdown в GitHub е възможността за директно споменаване на потребители и екипи в платформата. Просто въвеждате @, последвано от потребителското име или името на екипа, и GitHub изпраща известие до този акаунт, привличайки вниманието им към разговора.

Когато въведете символа @, GitHub показва списък с потребители и екипи, свързани с хранилището или нишката, и можете да филтрирате този списък, докато пишете. Използвайте клавишите със стрелки и натиснете Enter или Tab, за да приемете предложенията. За екипи използвайте формата @организация/име-на-екип и всички членове на екипа ще бъдат абонирани за нишката.

В допълнение към споменаванията, GitHub улеснява препращането към проблеми и заявките за изтегляне, като просто напишете #, последвано от число или част от заглавието. Появява се списък с предложени резултати, който можете да попълните по същия начин, както при споменаванията. Това значително ускорява навигацията между свързани разговори.

Ако вашето хранилище има конфигурирани персонализирани автоматично свързани препратки, някои външни нотации (като например идентификатори на билети в JIRA или Zendesk) също могат автоматично да бъдат конвертирани в кратки връзки. Тази настройка изисква администраторски права, но след като бъде активирана, тя позволява споделяне на данни между системите с минимални усилия.

И накрая, GitHub поддържа емоджита чрез код: въведете двоеточие, последвано от името на емоджито и завършете с друго двоеточие. Когато започнете да пишете, се появява списък с предложения, които можете да приемете с Tab или Enter. Включването на емоджита в коментарите ви помага да им придадете по-човешки вид, стига да не прекалявате с използването им във формална документация.

Бележки под линия и разширено съдържание

GitHub също поддържа бележки под линия, използвайки синтаксис, базиран на скоби, и идентификатор със символ каретка. На мястото, където искате препратката, вмъквате нещо като `<footnote>` и в края на документа дефинирате текста на тази бележка под линия със същия етикет, последван от двоеточие и съдържанието.

Бележките под линия могат да обхващат няколко реда и за да се наложат прекъсвания на редовете в рамките на дадена бележка под линия, в края на реда се използват двойни интервали, точно както в основната част на Markdown. При рендиране GitHub показва горен индекс върху текста и списък с бележки под линия в края, с обратни връзки за навигация между препратки и бележки под линия.

Друга разширена функция, предлагана от GitHub, са споменатите по-рано предупреждения (ЗАБЕЛЕЖКА, СЪВЕТ, ВАЖНО, ПРЕДУПРЕЖДЕНИЕ и ВНИМАНИЕ). Препоръчително е да се използват само когато са наистина необходими и да се избягва свързването на твърде много от тях, за да се предотврати претоварването на читателя. Те не могат да бъдат вложени в други сложни елементи, така че внимателното планиране на разположението им е от съществено значение.

Накрая, можете да помолите GitHub временно да скрие секции от рендирания Markdown, като ги обгърне в HTML коментари, или да игнорира обработката на определени символи с обратни наклонени черти. Това е особено полезно, когато документирате самия синтаксис на Markdown и трябва да покажете примери такива, каквито са, без интерпретация.

Markdown в Reddit: Snoomark и режим на редактиране

Reddit е дискусионна платформа, където почти всяка тема е добре дошла, организирана в subreddits. По отношение на форматирането, тя предлага два редактора: един за RTF текст, който е по-визуален, и друг за обикновен текст, базиран на Markdown. Ако искате да работите бързо и да имате прецизен контрол върху резултата, ще искате да използвате опцията Markdown.

По подразбиране Reddit обикновено активира редактора на богат текст, така че за да превключите в режим на маркиране, трябва да щракнете върху опцията за режим на маркиране в текстовото поле на публикация или коментар. Оттам можете да използвате директно синтаксиса на Snoomark.

Ако предпочитате редакторът на Markdown винаги да се зарежда, отидете в потребителските настройки, влезте в секцията „Настройки на емисията“ и активирайте опцията „По подразбиране за Markdown“ . По този начин редакторът на Markdown ще се отваря автоматично всеки път, когато започнете да пишете публикация или коментар, без да се налага да го променяте ръчно.

Reddit поддържа повечето основни и разширени функции на Markdown: заглавия, удебелен и курсивен шрифт, списъци, цитати, кодови блокове, връзки и някои свои собствени екстри, като спойлери. Той обаче има значителни недостатъци в сравнение с GitHub, особено при обработката на изображения , която е силно зависима от контекста и вида на редактора.

Синтаксис, поддържан от Reddit, и спойлери

Вариантът на Snoomark, използван от Reddit, включва много общи елементи с GitHub, така че ако вече сте експерт в Markdown за хранилища, прехвърлянето на тези знания към средата на Reddit е доста лесно. Можете да използвате заглавия, за да структурирате дълги публикации, номерирани или маркирани списъци, цитати, за да отговорите на други потребители, и блокове код, когато искате да покажете команди или технически фрагменти.

Една от забележителните разлики е начинът, по който Reddit обработва изображенията . Въпреки че в много случаи изображенията се качват през графичния интерфейс, а не директно със синтаксиса на Markdown, двигателят, който обработва текстовото съдържание, все още е Snoomark, така че форматирането около тези изображения наистина е базирано на Markdown.

Reddit, от друга страна, добавя допълнителни функции, които не са включени в стандартната спецификация, като например спойлери. Те позволяват текстът да бъде скрит зад слой, който потребителят може да разкрие с едно щракване. Технически, когато Reddit обработва спойлер, той го трансформира в комбинация от HTML, CSS класове и специфичен за платформата JavaScript.

Полученото HTML представяне на спойлер включва манипулатори, които контролират кога да се показва или скрива съдържанието, и макар теоретично нещо подобно да може да се напише с обикновен HTML, в Reddit това зависи от вътрешната му имплементация. Важното за вас като потребител е, че когато пишете, трябва да използвате само специфичния синтаксис за спойлери, предоставен от редактора, а Snoomark се грижи да го преведе в подходящата структура.

Накратко, Snoomark наследява много поведения от GitHub Flavored Markdown, но насочени към нуждите на дискусионната общност, а не към проектната документация. Въпреки това, ядрото остава същото: обикновен текст с прости символи, трансформиран в структурирано и четливо съдържание.

Овладяването на синтаксиса на Markdown в GitHub и Reddit прави писането на техническа документация, отварянето на добре обяснени проблеми, оставянето на ясни коментари по заявки за изтегляне и участието в дискусии в Reddit много по-ефективно. С няколко ключови правила – заглавия, акценти, списъци, цитати, блокове от код, връзки, изображения и специфични трикове като таблици, сгъваеми детайли, предупреждения, бележки под линия и спойлери – можете да преминете от писане на скучни съобщения към създаване на чисто, лесно за сканиране и професионално съдържание, без да щракнете нито един бутон на мишката.