Руководство по Markdown

Что такое Markdown?

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

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

Почему использовать Markdown?

Markdown невероятно прост и легок в изучении. Основы можно освоить всего за 10 минут. Символы форматирования интуитивны — звездочки для выделения, решетки для заголовков. Вы просто печатаете и добавляете простые символы для форматирования текста.

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

Markdown имеет широкую поддержку на различных платформах. GitHub, Reddit, Discord и Slack используют Markdown. Популярные приложения, такие как Obsidian, Notion и VS Code, поддерживают его нативно. Это делает его идеальным для документации, ведения заметок и веб-контента.

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

История развития Markdown

Начало: Vanilla Markdown (2004)

Markdown был создан Джоном Грубером в 2004 году при значительном участии Аарона Шварца. Грубер разработал его как простой способ написания с использованием легкочитаемого и легкописательного формата обычного текста, который можно было бы конвертировать в структурно корректный HTML. Это "ядро", которое изначально разработал и реализовал Джон Грубер, содержащее самый базовый синтаксис форматирования — то, что мы называем "базовым ванильным вкусом".

Базовый синтаксис (включает Vanilla Markdown):

  • •
    Заголовки: Использование символа # (# Заголовок)

  • •
    Выделение:

  • •
    Курсив: Использование * или _ для обертывания текста (*курсив* или _курсив_)
  • •
    Полужирный: Использование ** или __ для обертывания текста (**полужирный** или __полужирный__)

  • •
    Списки:

  • •
    Неупорядоченные списки: Использование *, - или + (- элемент)
  • •
    Упорядоченные списки: Использование цифр с точками (1. элемент)
  • •
    Ссылки: Использование [текст ссылки](адрес ссылки)
  • •
    Изображения: Использование ![описание изображения](адрес изображения)

  • •
    Блоки кода: Отступ пробелами (обычно 4 пробела или 1 Tab)

  • •
    Цитаты: Использование символа > (> Это цитата)
  • •
    Горизонтальные линии: Использование --- или ***

Проблема: Несогласованные реализации

Однако Vanilla Markdown не имел строгой формальной спецификации. Это привело к несогласованному поведению различных парсеров Markdown при обработке пограничных случаев.

Обработка пробелов: Например, в элементах списка, сколько пробелов отступа считается подсписком? Это 2 пробела, 3 пробела или 4 пробела? Разные парсеры могут иметь разные суждения.

Обработка переносов строк: В определенных ситуациях должен ли обычный перенос строки (\n) парситься как тег <br> (перенос строки), или его следует просто рассматривать как пробел в тексте? Это также может варьироваться в зависимости от парсера.

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

Решение: CommonMark (2014)

В сентябре 2014 года был представлен CommonMark для решения этих проблем несогласованности. Под руководством Джона МакФарлейна он предоставляет строгую спецификацию для Markdown.

CommonMark предоставляет точную спецификацию, где каждый пограничный случай четко определен. Он включает комплексный набор тестов с более чем 600 тестовыми случаями для обеспечения согласованности между реализациями. Спецификация предоставляет эталонную реализацию, которая служит стандартом для других парсеров. Он поддерживает обратную совместимость с большинством существующих Markdown-документов, обеспечивая при этом однозначный парсинг, где один и тот же вход всегда дает один и тот же выход во всех совместимых парсерах.

Расширенные варианты и дополнительные функции

Поскольку у пользователей были разные потребности, появились различные расширенные варианты Markdown для удовлетворения специфических требований.

GitHub Flavored Markdown (GFM) Дополнительный синтаксис:

  • •
    Таблицы: Использование синтаксиса с трубами для создания таблиц
  | Заголовок 1 | Заголовок 2 | Заголовок 3 |
  |-------------|-------------|-------------|
  | Ячейка 1    | Ячейка 2    | Ячейка 3    |
  | Ячейка 4    | Ячейка 5    | Ячейка 6    |
  • •
    Зачеркивание: Использование ~~ для обертывания текста (~~удаленный текст~~)

  • •
    Списки задач: Создание интерактивных флажков

  - [x] Выполненная задача
  - [ ] Невыполненная задача
  • •
    Огражденные блоки кода: Использование тройных обратных кавычек с указанием языка
  ```javascript
  function hello() {
    console.log("Привет, мир!");
  }
  ```
  • •
    Автоматическое связывание: URL-адреса и адреса электронной почты автоматически становятся кликабельными

Другие популярные расширения:

  • •
    Сноски: Использование синтаксиса [^1] для академического письма
  Это предложение со сноской[^1].
  [^1]: Это содержание сноски.

Результат: Это предложение со сноской¹.

  • •
    Математические выражения: Использование $E=mc^2$ для научных документов
  • •
    Сокращения эмодзи: Использование :smile: становится 😊

  • •
    Списки определений: Для глоссариев и технической документации

  Термин 1
  : Определение для термина 1
  
  Термин 2
  : Определение для термина 2
  : Другое определение для термина 2

Результат: Создает отформатированные списки с выделенными терминами и отступами определений

Как это работает?

Markdown следует простому трехэтапному рабочему процессу:

Шаг 1: Создание файла Markdown

Сначала вы создаете обычный текстовый файл с расширением .md или .markdown, используя любой текстовый редактор. Вы пишете свой контент, используя простые символы форматирования:

Шаг 2: Обработка инструментами Markdown

Ваш .md файл затем обрабатывается инструментами конвертации Markdown или процессорами. Эти инструменты читают ваш Markdown файл и конвертируют его в желаемый выходной формат.

Шаг 3: Вывод в различные форматы

Процессор Markdown может конвертировать ваш файл в несколько форматов:

Для веб-отображения:

  • •
    Конвертирует в HTML для веб-сайтов, блогов и веб-приложений

  • •
    Отображает отформатированный контент в браузерах с правильным стилем

Для документов:

  • •
    Конвертирует в PDF для печатных документов и отчетов

  • •
    Генерирует документы Word (.docx) для офисного использования
  • •
    Создает LaTeX для академических статей и публикаций

Для публикации:

  • •
    Генерирует электронные книги (формат EPUB)

  • •
    Создает слайды презентаций
  • •
    Производит веб-сайты документации

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

Дополнительные ресурсы

Основная документация

  • •
    Документация Markdown от Джона Грубера : Оригинальное руководство, написанное создателем Markdown. Обязательное чтение для понимания философии и базового синтаксиса.

  • •
    Википедия - Markdown : Всеобъемлющий обзор истории Markdown, вариаций и технических деталей.

  • •
    Руководство по Markdown : Всеобъемлющее руководство для начинающих с примерами и лучшими практиками для всех уровней навыков.