Что такое Markdown

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

Если не хотите проблем с отображением русского текста при чтении md-документа, используйте UTF при написании.

Немного о Markdown

Markdown создан в 2004 году Джоном Грубером и Аароном Шварцем. Цель создания - дать людям возможность создавать форматированный текст, который легко править и легко читать, а так же легко конвертировать в валидный HTML-код (или XHTML).

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

Грубер написал скрипт Markdown.pl (perl-скрипт), который конвертировал Markdown-текст в валидный HTML-код. Скрипт использовался как самостоятельный инструмент, и в качестве плагина к Blosxom, Movable Type, и как фильтр для BBEdit. Markdown так же реализован как perl-модуль Text::Markdown, доступный для скачивания на CPAN. Реализация на Perl распространяется под лицензией BSD-типа.

На данный момент доступны разнообразные реализации Markdown от сторонних разработчиков, в качестве модулей для всех популярных языков программирования, и плагинов для CMS-систем.

Markdown очень популярен, используется GitHub, GitBook, Reddit, Stack Overflow и многими другими проектами.

Файлы

Файлы документов, при создании которых был использован язык разметки Markdown - должны иметь расширение ".md" .

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

Для чтения Markdown-текста я использую удобный аддон для Firefox - Markdown Viewer.

Заголовки

Markdown поддерживает два стиля оформления заголовков "setext" и "atx".

Setext-стиль предполагает, что заголовки первого уровня подчеркиваются символом "=", а заголовки второго уровня - символом "-".

Пример:

This is an H1
=============
This is an H2
-------------

Количество "подчеркивающих" символов может быть любым.

Работа с заголовками и картинками в Markdown

Работа с заголовками и картинками в Markdown


Atx-стиль предполагает использование от 1 до 6 символов "#" в начале заголовка. Количество символов обозначает уровень заголовка. Пример:

# This is an H1
## This is an H2
###### This is an H6

При желании, в заголовках atx-стиля можно использовать "закрывающий" тег.

"Закрывающие" теги используются только для красоты, на усмотрение создателя документа, поэтому, в нет необходимости ставить сопоставимое первому блоку количество символов "#". Количество "#" перед заголовком определяет уровень заголовка, но после заголовка их может быть произвольное число, начиная от нуля.

Впрочем, наверняка существуют ограничения по длине конвертером Markdown или иные системные ограничения.

# This is an H1 #
## This is an H2 ##
### This is an H3 ######

Правильный заголовок:

# header1

Правильный заголовок:

Header
=======

Неправильный заголовок (отсутствует пробел между символом "#" и текстом заголовка):

#header1

Неправильный заголовок (в заголовках такого типа разрешено использовать только символы "=" и "-"):

Header
########

Внешний вид текста

Чтобы зачеркнуть текст, нужно использовать двойную тильду "~~".

Выделить текст курсивом можно с помощью одинарного символа "*" или "_". Выделение жирным шрифтом - "**" (двойная звездочка) или "__" (двойное подчеркивание).

Пример:

~~Зачёркнутый текст~~.

*Курсив* или по другому - _тоже курсив_ .

**Вложенность тоже допускается. _Одновременно жирный и курсив_**.

Чтобы добавить в текст маркированный список, нужно просто перечислить пункты списка, каждый пункт с новой строки, в начале строки символ "*", "-" или "+". В одном списке должны использоваться одинаковые маркеры. Изменение вида маркера приведет к тому, что при конвертации будет создано два разных списка.

Пример:

* первый элемент ненумерованного списка
* второй элемент ненумерованного списка
- первый элемент второго ненумерованного списка
+ первый элемент третьего ненумерованного списка

Работа с заголовками и списками в Markdown

Работа с заголовками и списками в Markdown


Для создания нумерованного списка, так же перечисляем пункты списка, каждый с новой строки. Вначале строки каждого пункта - число и следующая за ним точка. Интересно то, что нет необходимости соблюдать какой либо порядок в числах, если вы ошибетесь и после "2" напишете "9", при конвертации все равно будет автоматически соблюден правильный порядок чисел, и вместо "9" вы увидите значение "3".

Пример:

1. Элемент нумерованного списка
2. Элемент №2 того же списка
9. Элемент №3 списка — элементы нумеруются по порядку, цифра в начале строки не имеет значения

Добавить цитату (blockquote) можно с помощью символа ">" в начале строки.

Ссылки

Работа со ссылками в Markdown

Работа со ссылками в Markdown


Markdown поддерживает два вида ссылок: inline и reference. В обоих случаях текст ссылки ограничивается квадратными скобками.

Чтобы создать обычную (inline) ссылку, используйте квадратные и круглые скобки. В квадратных указывается текст ссылки, в круглых - URL. Можно добавить необязательный заголовок после URL.

[Inline-style link](http://example.com/)
[Inline-style link with title](http://example.com/ "Link title")

Reference-ссылки используют дополнительные квадратные скобки, внутри которого вы помещаете идентификатор ссылки. Идентификатор может быть как числом, так и строкой. Затем, в любом месте текста, вы сопоставляете идентификаторы ссылок и URL. Этот блок данных не будет отображаться при просмотре markdown-документа.

[Reference-style link][id]

[id]: http://example.com/ "Optional Title Here"

Вы можете дополнительно использовать пробел для разделения разных групп скобок:

This is [an example] [id] reference-style link.

GitHub и GitBook (да и многие другие современные конвертеры) поддерживают автоматическую установку ссылок. Вам достаточно просто добавить в текст нужный URL, без всяких скобок.

Правильная ссылка:

[Блог программиста](http://dev-lab.info)

Неправильная ссылка (там где нужны квадратные скобки - используются круглые, и наоборот):

(Блог программиста)[http://dev-lab.info]

Изображения


# Inline
![Alternative text](/path/to/img.jpg "Optional title")
# Reference
![Alternative text][id]
[id]: url/to/image "Optional title"

Форма добавления изображений очень похожа на добавление ссылок. Отличия:

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

Пример:

![Тут должна быть очень милая котейка](http://dev-lab.info/cat.png "Поделись с друзьями")

  • Если окажется, что картинка не может быть загружена, пользователь увидит
    на экране надпись "Тут должна быть очень милая котейка".
  • Если картинка была успешно загружена, при наведении курсора мыши на картинку пользователь увидит надпись "Поделись с друзьями".

Правильно:

![](http://dev-lab.info/cat.png)

Неправильно (нет восклицательного знака):

[My cat](http://dev-lab.info/cat.png)

Блоки кода

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

Чтобы добавить блок кода в документ, можно использовать отступы. Каждая строка блока кода должна начинаться минимум с 4х пробелов или 1 символа табуляции. Данный способ поддерживается не всеми реализациями Markdown-просмотрщиков.

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

Чтобы добавить небольшой блок кода прямо в строку, можно использовать выделение с помощью одинарного символа обратного апострофа.

Синтаксическое выделение кода

Добавление блока кода в markdown

Добавление блока кода в markdown


Вы можете включить синтаксическую подсветку для куска кода, указав название
используемого языка программирования:

Таблицы

Работа с таблицами в Markdown

Работа с таблицами в Markdown


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

Для создания таблиц используются символы "|", "-" и ":". "|" обозначает столбцы. При этом, крайние символы "|" не обязательны. Символ двоеточия помогает определить выравнивание текста в столбцах.

Заметка по мотивам вольного перевода "Learn Markdown" от Sammy P., Aaron O.