Что такое Markdown | Perl, Python - блог программиста

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

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

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

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

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

Ссылки

Работа со ссылками в 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"

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

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

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

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

Правильно:
![](https://dev-lab.info/cat.png)

Неправильно (нет восклицательного знака):
[My cat](https://dev-lab.info/cat.png)

Блоки кода

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

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

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

```
   my $var=12;
   print $var;
```

```

my $var=12;

print $var;

```

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

Объявляем новую переменную и присваиваем ей значение `my $var = 1;`.

1	Объявляем новую переменную и присваиваем ей значение `my $var = 1;`.

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

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

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

```perl
   my $var=12;
   print $var;
```

```perl

my $var=12;

print $var;

```

Таблицы

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

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

| Столбец 1 | Столбец 2 | Столбец 3 |
| ------------- |:-------------:| -----:|
| Текст | В этом столбце | Выравнивается |
| выравнивается | текст | по |
| по левому краю |  отцентрирован | правому краю |

| Столбец 1 | Столбец 2 | Столбец 3 |

| ------------- |:-------------:| -----:|

| Текст | В этом столбце | Выравнивается |

| выравнивается | текст | по |

| по левому краю | отцентрирован | правому краю |

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

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