Как быстро использовать Markdown на GitHub и Reddit

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

Если вы регулярно пишете на GitHub или проводите много времени на Reddit, освоение этих навыков будет для вас очень полезным. уценка Это одна из тех вещей, которая экономит вам часы и упрощает жизнь. Это очень легкий язык разметки, который позволяет быстро форматировать простой текст, не мучаясь с меню или кнопками, просто разместив несколько символов в нужных местах.

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

Что такое Markdown и почему он так полезен на GitHub и Reddit?

Маркдаун – это легкий язык разметки Разработан для того, чтобы сделать обычный текст удобным для чтения и написания, а также обеспечить легкое преобразование в HTML. На практике это означает, что вы можете писать обычный текст и добавлять специальные символы для создания заголовков, списков, таблиц, цитат, форматированного кода, ссылок или изображений.

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

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

Прелесть всего этого в том, что, используя единый синтаксис, вы можете писать тексты, которые хорошо выглядят как на GitHub, так и на Reddit, адаптируя лишь несколько деталей там, где каждая платформа работает по-разному. Изучите основные правила Это позволяет свободно перемещаться между двумя системами, не изучая ничего с нуля.

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

Одной из первых вещей, которые вам понадобятся, являются заголовкиКак на GitHub, так и на Reddit они используются для структурирования текста на разделы и подразделы.

В Markdown заголовок создаётся путём добавления перед текстом от одного до шести символов решетки (#): один для заголовка первого уровня, два для второго и так далее до шестого уровня. Например, в файле README.md на GitHub может быть что-то вроде: # Главный заголовок, ## Раздел, ### Подраздел, и т.д.

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

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

Это позволяет вам, например, размещать секцию. ## Пример раздела а затем создать ссылку на него в другом месте документа, используя следующий синтаксис: (#sample-section)или даже ссылаться на разделы, в заголовке которых присутствуют специальные символы, поскольку GitHub генерирует фрагмент кода, следуя этим правилам, и делает его доступным по тому же шаблону.

Выделение текста, цитаты.

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

Чтобы вставить текст NegritaЖирный текст заключается в двойные звездочки или двойные подчеркивания; для курсива используются одинарные звездочки или подчеркивания; чтобы зачеркнуть что-либо, по обе стороны от текста ставится двойная тильда (две тильды). Вложенные жирный и курсивный тексты также можно комбинировать, для применения обоих типов к целому разделу текста можно использовать три звездочки, или можно использовать 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 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-элемента. Этот предмет особенно полезен для зарядки. адаптивные изображения Эти параметры изменяются в зависимости от предпочтений пользователя в выборе темы оформления (светлая или темная). Используя медиа-запрос `prefers-color-scheme`, вы можете определить разные источники изображений для каждого режима, а также изображение по умолчанию для браузеров, которые не поддерживают эту функцию.

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

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

Таблицы, разворачивающиеся разделы и разделение контента.

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

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

Для упорядочивания длинного файла README можно использовать HTML-тег. Для создания сворачиваемых разделов. В этих разделах отображается краткое описание внутри метки. и позволяют пользователю расширять или сжимать дополнительный контент по мере необходимости. Обычно таблицы или блоки дополнительной информации заключают в себя. чтобы избежать чрезмерной нагрузки на глаз.

Если вы хотите, чтобы раздел отображался в развернутом виде по умолчанию, просто добавьте атрибут open к Этот метод очень удобен для группировки рейтингов, длинных списков или контента, который не является обязательным для первого прочтения, но удобно иметь под рукой.

Ещё один простой инструмент для организации информации — горизонтальная линейка. Она создаётся путём написания трёх или более тире на линии и служит для проведения разделительной линии между разделами, позволяя чётко отделить, например, описательный раздел от раздела ссылок или дополнительных примечаний.

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

Скрытые комментарии и управление форматированием

GitHub позволяет вам внедрять HTML-комментарии в Markdown, используя синтаксис Всё, что вы поместите в этот комментарий, не будет отображаться в отрендеренном контенте, но будет видно в исходном коде, поэтому он идеально подходит для внутренних заметок или списков дел.

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

Еще одна полезная функция — это персонажи побега обычно это интерпретируется как Markdown. Если вам нужно отображать звездочки, символы решетки или другие символы буквально, без форматирования, просто поставьте перед каждым из них обратную косую черту. Это позволяет, например, писать выражения, содержащие символы списков, без преобразования их в реальные списки.

При просмотре файла разметки на GitHub у вас есть возможность переключаться между отображаемым представлением и исходным кодом с помощью кнопки вверху (или открывать его в таких редакторах, как...). КронштейновОтключение интерпретации Markdown позволяет получить доступ к типичным функциям просмотра кода, таким как: ссылки на конкретные строкиЭто очень полезно, когда вам нужно указать конкретную часть файла README или любого файла .md.

Наконец, помните, что GitHub обрабатывает переносы строк по-разному в комментариях (issues, PR и т. д.) и в файлах .md. В комментариях переносы строк учитываются напрямую, тогда как в файлах Markdown необходимо добавить два пробела в конце строки, обратную косую черту или точку. чтобы принудительно совершить переход в пределах одного абзаца.

Списки, вложенные списки и списки дел

Списки — один из наиболее часто используемых элементов в Markdown, как на GitHub, так и на Reddit. Вы можете создавать списки. неупорядоченный перед каждым пунктом списка ставится дефис, звездочка или знак плюс. Все эти знаки отображаются аналогично маркированным спискам.

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

Вложенные списки создаются простым добавлением отступа к элементам, расположенным ниже. В редакторах с моноширинным шрифтом, таких как... Sublime TextПросто визуально выровняйте маркеры вложенных списков ниже первого символа текста в родительском элементе. В контекстах, подобных редактору комментариев GitHub, где шрифт не моноширинный, посчитайте количество символов перед текстом и используйте это количество пробелов для отступа.

Вы также можете создавать многоуровневые вложенные списки, при условии сохранения одинакового количества пробелов. Для очень сложных списков эта система требует некоторой практики, но как только вы освоите её, её будет очень легко применять.

GitHub также предлагает списки делЭти списки очень полезны для описания проблем, запросов на слияние и документации. Они создаются путем добавления перед ними дефиса, пробела и пары квадратных скобок с пробелом или крестиком внутри: для ожидающих задач и для выполненных задач. Эти списки отображаются с флажками, которые можно установить или снять с отметки в интерфейсе.

Если текст элемента списка дел начинается со скобок, их необходимо экранировать обратной косой чертой, чтобы избежать путаницы в парсере. Это небольшая деталь, но важная при написании описаний, начинающихся с чего-то вроде "(Необязательно)" или подобных.

Упоминания, ссылки и эмодзи на GitHub

Одно из преимуществ написания кода в формате Markdown на GitHub — это возможность использовать упоминает Отправляйте личные сообщения пользователям и командам на платформе. Просто введите @, а затем имя пользователя или название команды, и GitHub отправит уведомление на этот аккаунт, привлекая его внимание к беседе.

При вводе символа @ GitHub отображает список пользователей и команд, связанных с репозиторием или веткой обсуждения, и вы можете фильтровать этот список по мере ввода. Используйте клавиши со стрелками и нажимайте Enter или Tab, чтобы принять предложенные варианты. Для команд используйте формат @organization/team-name, и все члены команды будут подписаны на ветку обсуждения.

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

Если в вашем репозитории настроены пользовательские автоматически создаваемые ссылки, некоторые внешние обозначения (например, идентификаторы задач в JIRA или Zendesk) также могут автоматически преобразовываться в короткие ссылки. Для этой настройки требуются права администратора, но после включения она позволяет обмениваться данными между системами с минимальными усилиями.

Наконец, GitHub поддерживает эмодзи через код: введите двоеточие, затем название эмодзи и завершите еще одним двоеточием. По мере ввода текста появляется список подсказок, которые можно принять с помощью клавиши Tab или Enter. Включение эмодзи в комментарии делает их более человечными, если, конечно, вы не злоупотребляете ими в официальной документации.

Сноски и расширенный контент

GitHub также поддерживает Сноски Используйте синтаксис на основе скобок и идентификатор с чередующимся символом. В том месте, где вам нужна ссылка, вставьте что-то вроде , а в конце документа определите текст этой заметки с помощью того же тега, за которым следует двоеточие и содержимое.

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

Ещё одна расширенная функция, которую предлагает GitHub, это... alertas Эти элементы уже обсуждались (ПРИМЕЧАНИЕ, СОВЕТ, ВАЖНО, ПРЕДУПРЕЖДЕНИЕ и ОСТОРОЖНО). Рекомендуется использовать их только в случае крайней необходимости и избегать их слишком большого количества, чтобы не перегружать читателя. Они не могут быть вложены в другие сложные элементы, поэтому тщательное планирование их размещения имеет важное значение.

Наконец, вы можете попросить GitHub временно скрыть разделы сгенерированного Markdown, заключив их в HTML-комментарии, или игнорировать обработку определенных символов с помощью обратных косых черт. Это особенно полезно при документировании. Собственный синтаксис Markdown И вам нужно приводить примеры такими, какие они есть, без каких-либо интерпретаций.

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

Reddit — это платформа для обсуждений, где приветствуются практически любые темы, организованные в сабреддиты. Что касается форматирования, он предлагает два редактора: один для форматированного текста, более визуально привлекательного, и другой для обычного текста на основе Markdown. Если вам нужно работать быстро и иметь точный контроль над результатом, вам следует использовать опцию Markdown.

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

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

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

Синтаксис подтвержден пользователями Reddit и содержит спойлеры.

Вариант Markdown, используемый 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. С помощью нескольких ключевых правил — заголовков, выделения, списков, цитат, блоков кода, ссылок, изображений и специальных приемов, таких как таблицы, сворачиваемые детали, предупреждения, сноски и спойлеры — вы можете перейти от написания простого текста к созданию Чистый, удобный для просмотра и профессиональный контент не нажимая ни одной кнопки мыши.

Связанная статья:

Программное обеспечение для совместной работы: что это такое, типы и основные инструменты.