Шпаргалка по Markdown
Краткое справочное руководство по синтаксису Markdown — заголовки, списки, ссылки, блоки кода, таблицы и многое другое, с живым предпросмотром.
Как использовать
- Используйте оглавление слева для перехода к нужной категории синтаксиса.
- Каждая карточка показывает исходный синтаксис Markdown слева и результат рендеринга справа.
- Нажмите кнопку «Копировать», чтобы скопировать фрагмент в буфер обмена.
- Используйте эти фрагменты напрямую в GitHub, Notion, VS Code, Obsidian или любом редакторе Markdown.
Часто задаваемые вопросы
-
Что такое Markdown?
Markdown — это легковесный язык разметки, созданный Джоном Грубером в 2004 году. Он позволяет писать форматированный текст с помощью обычных текстовых символов — например, обрамление текста ** делает его жирным. Файлы Markdown преобразуются в HTML рендерерами, используемыми в GitHub, блог-платформах, инструментах для документации и приложениях для заметок.
-
Одинаков ли Markdown на всех платформах?
Базовый синтаксис в основном одинаков, но разные платформы поддерживают разные расширения. GitHub Flavored Markdown (GFM) добавляет списки задач, зачёркивание и таблицы. Obsidian поддерживает вики-ссылки. Некоторые платформы используют CommonMark в качестве стандарта. Шпаргалка сосредоточена на наиболее широко поддерживаемых функциях.
-
Как сделать перенос строки в Markdown?
Завершите строку двумя пробелами и нажмите Enter для создания мягкого переноса строки. Для разрыва абзаца оставьте пустую строку между двумя строками. Во многих рендерерах одиночный перенос строки без конечных пробелов воспринимается как пробел, а не как перенос.
-
Можно ли использовать HTML внутри Markdown?
Большинство рендереров Markdown разрешают встроенный HTML. Например, можно использовать <br> для переноса строки, <u>текст</u> для подчёркивания или <details> для раскрывающихся секций. Однако поддержка варьируется — некоторые рендерерами, ориентированные на безопасность, полностью удаляют HTML.
Что такое Markdown?
Markdown — это синтаксис простого текста, преобразуемый в HTML. Созданный Джоном Грубером в 2004 году, он был разработан таким образом, чтобы исходный текст был читаем сам по себе — необработанный текст должен выглядеть как форматированный даже без рендеринга. Сегодня он используется повсеместно: README-файлы GitHub, техническая документация, блог-платформы, приложения для заметок Obsidian и Notion, а также чат-инструменты Slack и Discord.
Основная идея проста: использовать обычные символы для обозначения форматирования. Знак # перед строкой делает её заголовком. Обрамление текста ** делает его жирным. Отступ строки четырьмя пробелами превращает её в блок кода.
Как помогает шпаргалка по Markdown
Даже опытные авторы иногда забывают точный синтаксис для выравнивания столбцов таблицы, вложенных списков или блоков кода с подсветкой синтаксиса. Шпаргалка служит быстрым справочником — вы видите исходный синтаксис и результат рендеринга рядом.
Шпаргалка охватывает:
- Заголовки — четыре уровня от h1 до h4
- Форматирование текста — жирный, курсив, зачёркивание, встроенный код, гиперссылки
- Списки — нумерованные, маркированные, вложенные и списки задач
- Ссылки и изображения — встроенные ссылки, ссылки с заголовком, изображения
- Цитаты — одиночные и вложенные
- Блоки кода — ограждённые с возможностью указания языка для подсветки синтаксиса
- Таблицы — с параметрами выравнивания столбцов
- Горизонтальные разделители — в качестве визуальных разделителей
Диалекты Markdown
CommonMark — это стандартизированная спецификация, устраняющая неоднозначности в оригинальной спецификации. GitHub, GitLab, Discourse и многие другие платформы следуют CommonMark или чему-то похожему.
GitHub Flavored Markdown (GFM) добавляет списки задач (- [x]), зачёркивание (~~текст~~), таблицы и автоссылки. Большинство платформ для кода поддерживают GFM или надмножество.
Для повседневного технического написания — README, документация, записи в блоге, заметки — стандартный CommonMark плюс расширения GFM охватывают практически всё необходимое.
Советы по написанию хорошего Markdown
Будьте последовательны в использовании маркеров списков. Выберите - или * для маркированных списков и придерживайтесь этого выбора. Смешивание допустимо, но сложнее читается в исходном виде.
Используйте пустые строки между блочными элементами. Пустая строка до и после заголовков, блоков кода и цитат обеспечивает корректный рендеринг в разных парсерах.
Предпочитайте ограждённые блоки кода отступам. Блоки с тройными обратными кавычками позволяют указать язык для подсветки синтаксиса и визуально более чёткие в исходнике.
Используйте описательный текст ссылки. [Нажмите здесь](url) хуже, чем [Спецификация Markdown](url) с точки зрения читаемости и доступности.