Як швидко використовувати Markdown на GitHub та Reddit

Інформатек Діджитал » Ресурси » Як швидко використовувати Markdown на GitHub та Reddit

Якщо ви регулярно пишете на GitHub або проводите багато часу на Reddit, майстеринг Markdown Це одна з тих речей, які заощаджують ваші години та спрощують ваше життя. Це дуже легка мова розмітки, яка дозволяє швидко форматувати звичайний текст, не борючись з меню чи кнопками, лише за допомогою кількох символів, розміщених у потрібних місцях.

На GitHub ви знайдете це скрізь: у файлах README.md з репозиторіїв, проблем, запитів на зняття змін, обговорень і навіть вашого власного профілю. Reddit, зі свого боку, використовує варіант під назвою Snoomark (Markdown у стилі Reddit), який успадковує значну частину синтаксису GitHub, з деякими унікальними особливостями та певними обмеженнями. Давайте розглянемо це крок за кроком і з багатьма прикладами, Як швидко використовувати Markdown на GitHub та Reddit і не пропустивши нічого важливого.

Що таке Markdown і чому він такий корисний на GitHub та Reddit?

Уцінка - це a легка мова розмітки Розроблено для того, щоб зробити звичайний текст легким для читання та написання, а також дозволяє легко конвертувати його в HTML. На практиці це означає, що ви можете писати звичайний текст і додавати спеціальні символи для створення заголовків, списків, таблиць, цитат, форматованого коду, посилань або зображень.

На GitHub використовується реалізація GitHub Flavored Markdown (GFM), яка розширює класичний синтаксис таблицями, списками справ, розширеним підсвічуванням коду, підтримкою кольорів, сповіщеннями та деякими дозволеними тегами HTML. Все це відтворюється автоматично у файлах .md та в полях коментарів платформи.

Reddit використовує власний процесор під назвою Snoomark, похідний від GFM. Він має багато спільних функцій (жирний шрифт, курсив, заголовки, списки, цитати, вбудований або блочний код, посилання тощо), але має… важливі характеристикиНаприклад, підтримка зображень більш обмежена залежно від контексту та додає власні елементи, такі як спойлери.

Краса всього цього полягає в тому, що за допомогою єдиного синтаксису ви можете писати тексти, які добре виглядатимуть як на GitHub, так і на Reddit, адаптуючи лише кілька деталей там, де кожна платформа працює по-різному. Вивчіть основні правила Це дозволяє вам вільно переміщатися в обох, не перевчаючись нічого з нуля.

Заголовки та структура контенту

Одна з перших речей, які ви будете використовувати, це заголовкиЯк на GitHub, так і на Reddit вони використовуються для структурування тексту на розділи та підрозділи.

У Markdown заголовок створюється шляхом додавання перед текстом від одного до шести символів решітки: один для заголовка першого рівня, два для другого рівня і так далі до шостого рівня. Наприклад, у файлі GitHub README.md може бути щось на кшталт: # Основна назва, ## Розділ, ### Підрозділ, І т.д.

Коли GitHub знаходить два або більше заголовків у файлі, він автоматично генерує зміст Доступно за допомогою значка «Структура» у верхній частині файлу. Кожен заголовок відображається як посилання, яке веде безпосередньо до цього розділу, що чудово підходить для довгих документів.

Крім того, кожен заголовок стає внутрішнім якорем, на який можна посилатися за допомогою фрагмента URL-адреси на основі тексту заголовка. Щоб згенерувати цей фрагмент, GitHub застосовує дуже специфічні правила: він перетворює літери на малі, замінює пробіли дефісами, видаляє знаки пунктуації та форматування (наприклад, курсив), обрізає зайві пробіли та, якщо результат збігається з іншим попереднім заголовком, додати числовий суфікс (-1, -2 тощо), щоб зробити його унікальним.

Це дозволяє вам робити такі речі, як розміщення розділу ## Зразок розділу а потім додайте посилання на нього з іншої точки документа за допомогою такого посилання: (#зразок-розділу)або навіть посилатися на розділи зі спеціальними символами в назві, оскільки GitHub генерує фрагмент коду, дотримуючись цих правил, і робить його доступним за тим самим шаблоном.

Наголос, виділений текст і цитати

Markdown дозволяє виділяти текст різними способами акцентЖирний, курсив, закреслений шрифт, нижній індекс, надрядковий шрифт або підкреслення. На GitHub типова таблиця стилів виглядатиме приблизно так, хоча ми підсумували її тут іншими словами:

Щоб вставити текст сміливийЖирний текст поміщається в подвійні зірочки або подвійне підкреслення; для курсиву використовуються одинарні зірочки або підкреслення; для закреслення чогось по обидва боки тексту ставиться подвійна тильда (дві тильди). Вкладені жирний шрифт і курсив також можна комбінувати, три зірочки можна використовувати для застосування обох до цілого розділу тексту, або можна використовувати теги HTML, такі як <br>. _{y ^{для нижніх та верхніх індексів, а також для підкреслення.}}

GitHub також дозволяє створювати цитати у стилі блокових цитат Якщо розмістити символ «більше ніж» (>) на початку рядка, цитований текст відображається з вертикальною смугою ліворуч і сірим кольором, що робить його чітко видимим. В один блок цитат можна включити кілька рядків, а цитати навіть можна вкладати, додавши більше символів > на початку.

Розширена форма цитування, яка існує лише на GitHub, – це сповіщення або застереженняВони базуються на тому ж синтаксисі блокових цитат, але перший рядок містить спеціальний маркер для позначення типу сповіщення. Наприклад, ви можете вказати `<alert>` для корисної інформації, `<helpful tips>` для практичних порад, `<key data>` для ключових даних, `<urgent notices>` для термінових попереджень та `<alert>` для попереджень про ризики або негативні наслідки. GitHub відображає кожен тип різним кольором та значком, що допомагає виділити критичну інформацію в документації.

Reddit також підтримує прості лапки з тим самим символом >, хоча йому бракує розширеної системи сповіщень GitHub. Навіть попри це, він залишається дуже корисним способом відповідаючи комусь, цитуючи частину його повідомлення не повторюючи його повністю.

Підсвічування коду, блоки та кольори

Як GitHub, так і Reddit дозволяють виділяти фрагменти коду в тексті за допомогою зворотних лапок. Для вбудованого коду ви обмежуєте слово або команду однією зворотною лапкою з кожного боку. Це ідеально підходить для виділення, наприклад, Git статус у реченні, чітко даючи зрозуміти, що це наказ.

Коли вам потрібен окремий блок коду, Markdown використовує три зворотні лапки: ви пишете рядок із трьома зворотними лапками, потім код на окремих рядках і завершуєте рядок ще трьома зворотними лапками. На GitHub, якщо ви також вказуєте мову одразу після першої зворотної лапки, вона застосовується... підсвічування синтаксису з кольорами та форматом, характерними для цієї мови.

GitHub також пропонує спеціальну функцію для підсвічування колірні значення у зворотних лапках. Якщо ви вводите колір у шістнадцятковому, RGB або HSL форматі між зворотними анотаціями, платформа додає невеликий індикатор кольору поруч із текстом. Наприклад, якщо колір фону у світлому режимі — #ffffff, а в темному — #000000, виділення цих кодів дозволяє швидко побачити, який є який.

Щодо візуалізації коду та таблиць, GitHub дозволяє ввімкнути фіксований моноширинний шрифт у всіх полях коментарів, щоб зробити роботу з технічним текстом зручнішою. ​​Якщо ви редагуєте багато фрагментів коду у своєму браузері або в редакторах, таких як Код Visual StudioУвімкнення цієї опції полегшує вирівнювання та читання. набагато більш послідовним.

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 Цей предмет особливо корисний для заряджання адаптивні зображення Вони змінюються відповідно до налаштувань теми користувача (світла чи темна). Використовуючи медіа-запит `prefers-color-scheme`, ви можете визначити різні джерела зображень для кожного режиму та зображення за замовчуванням для браузерів, які не підтримують цю функцію.

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

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

Таблиці, розкладні секції та розділення вмісту

Одним із найкорисніших покращень у GitHub Flavored Markdown є підтримка… столиВи можете впорядкувати дані в рядки та стовпці, використовуючи вертикальні смуги для розділення комірок та пунктирну лінію для позначення заголовка. Ви також можете вирівняти стовпці праворуч, ліворуч або по центру, використовуючи двокрапку в рядку-роздільнику.

Таблиці дуже корисні для представлення списків мов програмування, використаних фреймворків, запланованих завдань, порівняння функцій або будь-якої іншої інформації, яка виграє від матричної структури. GitHub відтворює ці таблиці у чистому та читабельному стилі.

Щоб упорядкувати довгий файл README, можна використовувати тег HTML щоб створити розділи, що згортаються. У цих розділах відображається зведення всередині підпису і дозволяють користувачеві розширювати або звужувати додатковий вміст за потреби. Зазвичай таблиці або блоки вторинної інформації вкладаються всередину щоб уникнути перевантаження очей.

Якщо ви хочете, щоб розділ за замовчуванням відображався розгорнутим, просто додайте атрибут open до Цей метод дуже практичний для групування рейтингів, довгих списків або контенту, який не є важливим для першого читання, але зручний для швидкого доступу.

Ще одним простим інструментом для організації інформації є горизонтальна лінійка. Вона створюється шляхом написання трьох або більше тире на лінії та служить для проведення розділової лінії між розділами, дозволяючи чітко відокремити, наприклад, описовий розділ від розділу посилань або додаткових приміток.

Ці правила можна поєднувати з цитатами в кінці документа, щоб виділити натхненні фрази, нагадування або ключові повідомлення. Типовим прикладом може бути розміщення мотиваційної цитати в кінці вашого README-файлу профілю, відформатованої як блочна цитата після роздільної лінії.

Приховані коментарі та керування форматом

GitHub дозволяє вам представити HTML-коментарі у Markdown з використанням синтаксису Все, що ви розмістите всередині цього коментаря, не буде відображатися у відображеному контенті, але буде видно у вихідному коді, тому він ідеально підходить для внутрішніх нотаток або завдань.

Наприклад, у файлі README профілю ви можете додати коментар на кшталт того, що вам потрібно пізніше розширити розділ «Про мене» або переглянути таблицю застарілих технологій, але ніхто, хто відвідує профіль, не бачить її безпосередньо.

Ще одна корисна функція полягає в тому, що символи керування що зазвичай інтерпретується як Markdown. Якщо вам потрібно відобразити зірочки, символи решітки або інші символи буквально без їх форматування, просто поставте перед кожним із них зворотну скісну риску. Це дозволяє, наприклад, писати вирази, що містять символи списків, не перетворюючи їх на фактичні списки.

Коли ви переглядаєте файл розмітки на GitHub, у вас є можливість перемикатися між відображенням відображення та вихідним кодом за допомогою кнопки у верхній частині (або відкривати його в редакторах, таких як КронштейниВимкнення інтерпретації Markdown надає вам доступ до типових функцій перегляду коду, таких як посилання на конкретні лініїЦе дуже корисно, коли ви хочете вказати точну частину README або будь-якого файлу .md.

Зрештою, пам’ятайте, що GitHub по-різному обробляє розриви рядків у коментарях (проблеми, PR тощо) та у файлах .md. У коментарях розриви рядків враховуються безпосередньо, тоді як у файлах Markdown вам потрібно додати два пробіли в кінці рядка, зворотну скісну риску або крапку. щоб примусово здійснити перехід у межах того самого абзацу.

Списки, вкладені списки та списки справ

Списки є одними з найбільш використовуваних елементів у Markdown, як на GitHub, так і на Reddit. Ви можете створювати списки невпорядкований шляхом розміщення дефісу, зірочки або знака «плюс» перед кожним елементом списку. Усі ці позначки відображаються аналогічно до маркованих списків.

Для створення списків наказавКожен рядок пронумеровано числом, після якого йдуть крапка та пробіл. Хоча порядок чисел не обов'язково має бути ідеальним (GitHub зазвичай його перераховує), гарною ідеєю є підтримувати послідовну нумерацію, щоб зробити вихідний код читабельним.

Вкладені списки створюються простим додаванням відступів до елементів під ними. У моноширинних редакторах, таких як Sublime TextПросто візуально вирівняйте вкладені маркери списку під першим символом тексту в батьківському елементі. У таких контекстах, як редактор коментарів GitHub, де шрифт не є моноширинним, порахуйте кількість символів перед текстом і використовуйте цю кількість пробілів для відступів.

Ви також можете створювати кілька рівнів вкладеності, якщо дотримуватися узгодженості в кількості пробілів. Для дуже складних списків ця система вимагає трохи практики, але як тільки ви звикнете до неї, її дуже швидко застосовувати.

GitHub також пропонує списки справВони дуже корисні для задач, запитів на зняття (pull requests) та документації. Вони створюються шляхом додавання дефісу, пробілу та пари квадратних дужок з пробілом або символом "x" всередині: для завдань, що очікують на виконання, та для завершених завдань. Ці списки відображаються з прапорцями, які можна встановити або зняти з інтерфейсу.

Якщо текст елемента списку справ починається з дужок, його потрібно екранувати зворотною скісну рискою, щоб уникнути плутанини в синтаксичному аналізаторі. Це невелика деталь, але важлива під час написання описів, які починаються з чогось на кшталт «(Необов’язково)» або подібного.

Згадки, посилання та емодзі на GitHub

Одна з переваг написання текстів у Markdown на GitHub полягає в можливості використання згадує Надсилайте прямі повідомлення користувачам і командам на платформі. Просто введіть @, а потім ім'я користувача або назву команди, і GitHub надішле сповіщення цьому обліковому запису, привертаючи їхню увагу до розмови.

Коли ви вводите символ @, GitHub відображає список користувачів і команд, пов’язаних із репозиторієм або потоком, і ви можете фільтрувати цей список під час введення. Використовуйте клавіші зі стрілками та натискайте Enter або Tab, щоб прийняти пропозиції. Для команд використовуйте формат @організація/назва-теаду, і всі учасники команди будуть підписані на потік.

Окрім згадок, GitHub сприяє проблеми з посиланнями та запити на зняття Просто введіть #, а потім число або частину заголовка. З’явиться список запропонованих результатів, який можна заповнити так само, як і згадки. Це значно пришвидшує навігацію між пов’язаними розмовами.

Якщо у вашому репозиторії налаштовано користувацькі автозв'язані посилання, деякі зовнішні нотації (такі як ідентифікатори заявок JIRA або Zendesk) також можуть автоматично перетворюватися на короткі посилання. Цей параметр вимагає прав адміністратора, але після ввімкнення він дозволяє обмін даними між системами з мінімальними зусиллями.

Зрештою, GitHub підтримує емодзі через код: введіть двокрапку, потім назву емодзі та завершіть ще однією двокрапкою. Коли ви починаєте вводити текст, з’являється список варіантів, які можна прийняти за допомогою Tab або Enter. Включення емодзі до ваших коментарів допомагає надати їм більш людського вигляду, якщо ви не зловживаєте ними у формальній документації.

Виноски та розширений контент

GitHub також підтримує Виноски Використання синтаксису на основі дужок та ідентифікатора з переплетеними символами. У місці, де потрібно розмістити посилання, ви вставляєте щось на кшталт , а в кінці документа визначаєте текст цієї примітки за допомогою того самого тегу, а потім двокрапку та вміст.

Виноски можуть охоплювати кілька рядків, а для примусового перенесення рядків у виносці в кінці рядка використовуються подвійні пробіли, як і в основній частині Markdown. Під час рендерингу GitHub відображає верхній індекс у тексті та список виносок у кінці зі зворотними посиланнями для навігації між посиланнями та виносками.

Ще одна розширена функція, яку пропонує GitHub, це... оповіщення Вони вже обговорювалися (ПРИМІТКА, ПОРАДА, ВАЖЛИВО, ПОПЕРЕДЖЕННЯ та УВАГА). Бажано використовувати їх лише за дійсної необхідності та уникати нарощування великої кількості елементів разом, щоб не перевантажити читача. Їх не можна вкладати в інші складні елементи, тому ретельне планування їх розміщення є важливим.

Зрештою, ви можете попросити GitHub тимчасово приховати розділи відображеного Markdown, обгорнувши їх HTML-коментарі, або ігнорувати обробку певних символів за допомогою зворотних слешів. Це особливо корисно під час документування. Власний синтаксис Markdown І потрібно показувати приклади такими, якими вони є, без інтерпретацій.

Markdown на Reddit: Snoomark та режим редагування

Reddit — це платформа для обговорення, де вітається майже будь-яка тема, організована в subreddits. Що стосується форматування, вона пропонує два редактори: один для форматованого тексту, який є більш візуальним, та інший для звичайного тексту на основі Markdown. Якщо ви хочете працювати швидко та мати точний контроль над результатом, вам знадобиться опція Markdown.

За замовчуванням Reddit зазвичай активує редактор форматованого тексту, тому, щоб переключитися в режим розмітки, потрібно натиснути на опцію Режим уцінки у текстовому полі допису чи коментаря. Звідти ви можете безпосередньо використовувати синтаксис Snoomark.

Якщо ви бажаєте, щоб редактор Markdown завжди завантажувався, вам слід перейти до налаштувань користувача, увійти до розділу «Налаштування стрічки» та активувати відповідну опцію. За замовчуванням використовується уцінкаТаким чином, щоразу, коли ви починаєте писати допис чи коментар, редактор Markdown відкриватиметься автоматично, без необхідності змінювати його вручну.

Reddit підтримує більшість базових та розширених функцій Markdown: заголовки, жирний та курсивний шрифт, списки, цитати, блоки коду, посилання та деякі власні додаткові елементи, такі як спойлери. Однак, він має суттєві недоліки порівняно з GitHub, особливо в управління зображеннямищо досить сильно залежить від контексту та типу редактора.

Синтаксис, що підтримується Reddit, та спойлери

Варіант Snoomark, який використовується Reddit, містить багато спільних елементів з GitHub, тому, якщо ви вже володієте Markdown для репозиторіїв, перенесення цих знань у середовище Reddit досить просте. Ви можете використовувати заголовки для структурування довгих постів, нумеровані або марковані списки, цитати для відповіді іншим користувачам та блоки коду, коли потрібно відображати команди або технічні фрагменти.

Одна з помітних відмінностей полягає в тому, як Reddit обробляє образністьХоча в багатьох випадках зображення завантажуються через графічний інтерфейс, а не безпосередньо з використанням синтаксису Markdown, движком, який обробляє текстовий вміст, все ще є Snoomark, тому форматування навколо цих зображень базується на Markdown.

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

Отримане HTML-представлення спойлера містить обробники, які контролюють, коли показувати або приховувати контент, і хоча теоретично щось подібне можна було б написати за допомогою простого HTML, на Reddit це залежить від його внутрішньої реалізації. Важливо для вас як користувача, щоб під час написання вам потрібно було використовувати лише специфічний синтаксис спойлерів, наданий редактором, і Снумарк відповідає за його переклад до відповідної структури.

Коротше кажучи, Snoomark успадковує багато моделей поведінки від GitHub Flavored Markdown, але орієнтований на потреби спільноти обговорень, а не на проектну документацію. Незважаючи на це, суть залишається незмінною: звичайний текст із простими символами, перетворений на структурований та читабельний контент.

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