Markdown
Markdown
Markdown1 (маркдаун) — облегчённый язык разметки. Первоначально создан Джоном Грубером (англ. John Gruber) и Аароном Шварцем, целью которых являлось создание максимально удобочитаемого и удобного в публикации облегчённого языка разметки.
Маркдаун обладаем множеством вспомогательных функций, например, автоматической сборкой содержимого документа и генераций сносок. В diy.ru мы используем его еще и для того, чтобы отделить работу редакторов от работы дизайнеров, поскольку дизайн сайта может со временем меняться, поэтому крайне важно чтобы текст статей не содержал элементов стилей.
Маркдаун не является заменой HTML
Маркдаун прежде всего создавался для написания текстов с последующей конвертацией в разметку. Для редактора синтаксис маркдауна исчерпывающий, однако может возникнуть необходимость использовать html, например, для размещения скриптов в теле статьи. В случае необходимости использования html, пожалуйста, не исползуйте — наверняка вы делаете что-то не так. Лучше обратитесь к «программисту».
В качестве справочника по html рекомендуется htmlbook.ru.
Содержание
Маркдаун может генерировать содержание статьи автоматически основываясь на заголовках, при этом якоря создаются также автоматически. В месте вывода содержания укажите тег [TOC]. В результате, вы получите вот такой список:
Форматирование текста
Блочные элементы
В маркдаун все блочные элементы (заголовки, списки, абзацы и т.д.) — все, что визуально начинается с новой строки отбивается пустой строкой.
Это заголовок <h1>
------------------
Это абзац <p>
И это абзац <p>
Перенос строки
Перенос строки всегда игнорируется. Это делается для того, чтобы, например, была возможность при наборе держать определенную длину строки, скажем в 80 символов.
Т.к. маркдаун создавался с целью быть удобночитаемым, его нередко используют в текстовых документах и для комфорта читателя лучше не давать тексту расплываться соплёй по экрану. Например, вот так выглядит официальная документация по маркдауну в текстовом виде.
Для переноса строки внутри абзаца нужно использовать два пробела ●● в конце строки.
Это абзац.●●
Это новая строка в том же абзаце.
Технически используется тег <br> (перенос строки).
UPD: теперь возможно использование переноса строки.
Начертания текста
Курсив обрамляется звездочкой * с обеих сторон текста — *Курсив*.
Жирное начертание двумя ** — **Жирное начертание**.
Жирный курсив, соответственно, тремя *** — ***Жирный курсив***.
Заголовки
Заголовок первого уровня
========================
Заголовок второго уровня
------------------------
Количество «черточек» не имеет значения.
Существует и универсальный синтаксис использующий хеш-тег #.
# Заголовок первого уровня
## Заголовок второго уровня
### Заголовок третьего уровня
…
###### Заголовок шестого уровня
Таблицы
Это проще чем <table>:
Item | Value | Quantity
:-------- |:-----:| -------:
Computer | 1600 | 3
Phone | 12 | 2
Pipe | 1 | 1
| Item | Value | Quantity |
|---|---|---|
| Computer | 1600 | 3 |
| Phone | 12 | 2 |
| Pipe | 1 | 1 |
Цитаты
Для обозначения цитат достаточно поставить знак > в начале строки.
> Буря мглою небо кроет,
Вихри снежные крутя;
*«Зимний вечер», А.С.Пушкин*
Буря мглою небо кроет,
Вихри снежные крутя;
«Зимний вечер», А.С.Пушкин
Цитаты можно вкладывать друг в друга.
> This is the first level of quoting.
>
> > This is nested blockquote.
>
> Back to the first level.
Иногда в цитатах могут быть пустые строки, что в маркдауне означает «новый абзац».
В таком случае отмечайте каждую строку символом >.
> Буря мглою небо кроет,
> Вихри снежные крутя;
>
> *«Зимний вечер», А.С.Пушкин*
Буря мглою небо кроет,
Вихри снежные крутя;
«Зимний вечер», А.С.Пушкин
Внимание! Цитаты на сайте отключены. Этот синтаксис используется для создания врезок.
Списки
Ненумерованный список
Для обозначения ненумерованного списка нужно поставить любой из этих символов -*+ перед каждым элементом списка.
- Red
- Green
- Blue
- Red
- Green
- Blue
Нумерованный список
Для нумерованного списка его элементы нумеруется.
3. Раз
1. Два
2. Три
- Раз
- Два
- Три
Порядок нумерации и само число не имеют значения, список будет пронумерован согласно порядку записи элементов.
Списки могут содержать в себе параграфы и цитаты. При этом семантически они действительно будут вложены тегами друг в друга.
1. This is a list item with two paragraphs. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
sit amet velit.
> This is a blockquote
> inside a list item.
2. Suspendisse id sem consectetuer libero luctus adipiscing.
-
This is a list item with two paragraphs. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
mi posuere lectus.Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
sit amet velit.This is a blockquote
inside a list item. -
Suspendisse id sem consectetuer libero luctus adipiscing.
Бывают разные случаи:
1987\. Какой чудный год.
Чтобы это не превратилось в элемент списка, необходимо экранировать точку с помощью символа \. Во всех подобных случаях экранируйте синтаксис.
Горизонтальная линия
Можно делать разными способами отбивая пустой строкой до и после.
* * *
***
- - -
---------------------------------------
Ссылки и изображения
Имеют похожий синтаксис.
[название ссылки](http://diy.ru "опциональный тайтл ссылки")
Как видно, у картинок вначале идет восклицательный знак !.
Можно вкладывать друг в друга — вместо названия ссылки вставляется картинка и ссылка становится кликабельной.
Изображения в ссылках
[](http://static.diy.ru/media/uploaded/bn/2012/12/19/valyanie-iz-shersti-novogodnyaya-yolka-svoimi-rukami.jpg)
Ссылки сносками
Ссылки и картинки имеют дополнительный удобный синтаксис. Вместо «путей» можно использовать «теги», например, сначала написать текст разметив что и где должно находиться, а затем в виде сноски указать ссылку, при этом сноски визаульно в статье не отображаются.
I get 10 times more traffic from [Google][1] than from
[Yahoo][2] or [MSN][3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
Если название ссылки совпадает с названием тега, можно сделать и так:
I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
При этом регистр не имеет значения. Картинки могут также:
![Alt text][id]
[id]: http://static.diy.ru/media/uploaded/bn/2012/12/19/valyanie-iz-shersti-novogodnyaya-yolka-svoimi-rukami.jpg "logo"
Сноски
Маркдаун может генерировать сноски. Для этого нужно после слова поставить тег сноски [^название_тега] и указать самоу сноску новым абзацем в любом месте документа [^название_тега]: текст тега. Сами сноски автоматически выведутся в конце документа.
**Markdown**[^wiki_markdown] — облегчённый язык разметки.
[^wiki_markdown]: [ru.wikipedia.org](/wiki/Markdown "ru.wikipedia.org")
Определения
В html есть специальный синтаксис для «определений» <dl><dt><dd>.
Apple
: Pomaceous fruit of plants of the genus Malus in
the family Rosaceae.
Orange
: The fruit of an evergreen tree of the genus Citrus.
- Apple
- Pomaceous fruit of plants of the genus Malus in
the family Rosaceae. - Orange
- The fruit of an evergreen tree of the genus Citrus.
Прочее
В маркдауне есть умный синтаксис для ссылок и адресов электронной почты:
<http://example.com/> и <address@example.com>
Во втором случае к ссылке добавилось mailto:, что позволяет по клику запустить почтовую программу.
Несколько моментов
- перенос строки игнорируется
- возможно комбинировать элементы синтаксиса, например, можно вставлять изображения в ссылки, объединять курсив с болдом — html необходимо знать, например, для работы с таблицами — внимательно с синтаксисом, особенно с отступами, иногда склеенные блоки приводят к непредвиденным результатам
Полезные ссылки
- Онлайн редактор StackEdit — имейте ввиду, некоторые возможности маркдауна представленные в нем не доступны на сайте diy.ru, например, выравнивание содержимых ячеек таблицы, и наоборот что-то в нем может работать не так как ожидалось, все это связано разницей в реализации синтаксиса маркдауна.
- Редактор для windows
- Синтаксис маркдауна