В разделе рассмотрен синтаксис классической реализации Markdown от Джона Грубера [John Gruber].
<h1> - <h6>;<blockquote>;<ul>, <ol>, <li>;<em>, <strong> ;<hr>;<a>;<img>;Markdown не является заменой HTML или даже близкой к ней. Его синтаксис очень мал и соответствует только очень небольшому подмножеству HTML-тегов. Идея состоит не в том, чтобы создать синтаксис, облегчающий вставку HTML-тегов. Идея Markdown состоит в том, чтобы облегчить чтение, написание и редактирование документов, предназначенных для размещения в интернете. HTML - это формат публикации, Markdown - это запись формата. Таким образом, синтаксис форматирования Markdown только решает проблемы, которые могут быть переданы в обычном тексте.
Для любой разметки, которая не покрывается синтаксисом Markdown, можно просто использовать теги HTML.
Единственные ограничения заключаются в том, что HTML-элементы уровня блока - например <div>, <table>, <pre>, <p>, и т. д. - должны быть отделены от окружающего контента пустыми строками, а начальные и конечные теги блока не должны иметь отступов с табуляциями или пробелами. Парсеры Markdown, не должны добавлять дополнительные (нежелательные) теги <p> вокруг тегов HTML-блока.
Например, чтобы добавить таблицу HTML в разметку Markdown:
This is a regular paragraph. <table> <tr> <td>Foo</td> </tr> </table> This is another regular paragraph.
Обратите внимание, что синтаксис форматирования Markdown не обрабатывается на уровне блока. Например, можно использовать стиль Markdown emphasis внутри HTML-тегов. HTML-блок.
HTML-теги уровня span - например <span>, <cite> , или <del> - могут использоваться/вставляться в любом месте абзаца Markdown, элемента списка или заголовка. Если необходимо, то можно использовать HTML-теги вместо разметки Markdown. Например, можно использовать HTML-теги <a> или <img> вместо предлагаемого синтаксиса Markdown ссылок или изображений.
В отличие от HTML-тегов блочного уровня, в тегах уровня span - синтаксис Markdown обрабатывается.
В HTML есть два символа, которые требуют специального обращения: < и &. Левые угловые скобки используются для обозначения начала HTML-тегов, а амперсанды используются для обозначения HTML-сущностей. Если необходимо использовать их как литеральные символы, то надо экранировать их как HTML-сущности, например <, и &.
Если надо написать о "AT&T", то нужно писать как "AT&T". Так же нужно избегать амперсандов в URL-адресах. Таким образом:
http://images.google.com/images?num=30&q=larry+bird нужно закодировать URL-адрес следующим образом: http://images.google.com/images?num=30&q=larry+bird
<h1> - <h6>.Markdown поддерживает два стиля заголовков: Setext и atx.
Заголовки в стиле Setext подчеркиваются с помощью знаков равенства (для заголовков первого уровня <h1>) и тире (для заголовков второго уровня <h2>). Например:
This is an H1 ============= This is an H2 -------------
Будет работать любое количество подчеркивающих = или -.
Заголовки в стиле atx используют 1 - 6 символов хэша в начале строки, соответствующие уровням заголовка <h1> - <h6>. Например:
# This is an H1 ## This is an H2 ###### This is an H6
При желании можно “закрыть” заголовки в стиле atx. Это чисто косметическое средство - можно использовать его, если считаете, что это выглядит лучше. Закрывающие хэши даже не должны совпадать с количеством хэшей, используемых для открытия заголовка. (Количество открывающихся хэшей определяет уровень заголовка) :
# This is an H1 # ## This is an H2 ## ### This is an H3 ######
<blockquote>.Markdown использует символы > для блоков с цитатами <blockquote>. Если знакомы с цитированием отрывков текста в сообщении электронной почты, то знаете, как создать блоков с цитатой в Markdown. Блок с цитатой выглядит заметнее и наглядней, если жестко обернуть текст и поставить символ > перед каждой строкой:
> This is a blockquote 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. Suspendisse > id sem consectetuer libero luctus adipiscing.
Markdown позволяет ставить символ > только перед первой строкой абзаца с цитатой:
> This is a blockquote 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. Suspendisse id sem consectetuer libero luctus adipiscing.
Блоки с цитатами <blockquote> можно вкладывать друг в друга, добавив дополнительные уровни с помощью символа >:
> This is the first level of quoting. > > > This is nested blockquote. > > Back to the first level.
Блок с цитатой может содержать другие элементы Markdown, включая заголовки, списки и блоки кода:
> ## This is a header. > > 1. This is the first list item. > 2. This is the second list item. > > Here's some example code: > > return shell_exec("echo $input | $markdown_script");
<ul>, <ol>, <li>.Markdown поддерживает упорядоченные (нумерованные) и неупорядоченные (маркированные) списки.
Неупорядоченные списки используют символы звездочки *, плюсы + и дефисы - (взаимозаменяемо) в качестве маркеров списков:
* Red * Green * Blue
эквивалентно:
+ Red + Green + Blue
и эквивалентно:
- Red - Green - Blue
В упорядоченных списках используются числа, за которыми следуют точки:
1. Bird 2. McHale 3. Parish
Важно отметить, что фактические числа, которые используются для номера списка, не влияют на выходные данные HTML. Разметка Markdown производит из приведенного выше списка следующий HTML-код:
<ol> <li>Bird</li> <li>McHale</li> <li>Parish</li> </ol>
Если список написан в разметке/документе Markdown вот так:
1. Bird 1. McHale 1. Parish
или даже так:
3. Bird 1. McHale 8. Parish
то все равно, на выходе, получится точно такой же HTML. Если необходимо, то можно использовать порядковые номера в своих нумерованных списках Markdown, что-бы числа в источнике совпадали с числами в опубликованном HTML. Но если хотите, то можно быть ленивым.
Если использовать ленивую нумерацию списков, то все равно следует начинать список с цифры 1. Возможно в будущем, Markdown может поддерживать запуск упорядоченных списков с произвольного номера.
Маркеры списка обычно начинаются с левого поля, но могут иметь отступ до трех пробелов. Маркеры списка должны сопровождаться одним или несколькими пробелами или табуляцией.
Для того, что бы оформление списка выглядели красиво, их можно обернуть висячими отступами:
* 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. Suspendisse id sem consectetuer libero luctus adipiscing.
Но можно этого не делать:
* 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. Suspendisse id sem consectetuer libero luctus adipiscing.
Если элементы списка разделены пустыми строками, то Markdown обернет элементы в теги <p> при выводе HTML. Например:
* Bird * Magic
преобразуется в следующий HTML:
<ul> <li>Bird</li> <li>Magic</li> </ul>
Но следующая разметка:
* Bird * Magic
преобразуется в следующий HTML:
<ul> <li><p>Bird</p></li> <li><p>Magic</p></li> </ul>
Элементы списка могут состоять из нескольких абзацев. Каждый последующий абзац в элементе списка должен иметь отступ либо в 4 пробела либо в одну табуляцию:
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. 2. Suspendisse id sem consectetuer libero luctus adipiscing.
Будет выглядеть красиво, если сделать отступы в каждой строке последующих абзацев, но и здесь это делать не обязятельно:
* This is a list item with two paragraphs. This is the second paragraph in the list item. You're only required to indent the first line. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. * Another item in the same list.
Чтобы поместить блок с цитатой в элемент списка, то она (цитата) должна быть задана следующим образом: символы разделители > должны иметь отступы:
* A list item with a blockquote: > This is a blockquote > inside a list item.
Чтобы поместить блок кода в элемент списка, он должен иметь двойной отступ - 8 пробелов или две табуляции:
* A list item with a code block: <code goes here>
Стоит отметить, что можно случайно сгенерировать на выходе упорядоченный список, написав что-то вроде этого:
1986. What a great season.
Чтобы избежать такого поведения, можно использовать обратную косую черту \ - экранировать точку:
1986\. What a great season.
<u>, <em>, <strong> .Markdown рассматривает звездочки * и подчеркивания _ как индикаторы акцента (привлечения внимания) какого то участка текста.
_ будет обернут HTML-тегом <u>, * будет обернут HTML-тегом <em>, * или _ будет обернут с помощью HTML-тега <strong>._single underscores_ *single asterisks* **double asterisks** __double underscores__
будет производить:
<u>single asterisks</u> <em>single underscores</em> <strong>double asterisks</strong> <strong>double underscores</strong>
Можно использовать любой стиль, который предпочитаете, единственное ограничение заключается в том, что для открытия и закрытия акцента должен использоваться один и тот же символ.
Акцент может быть использован в середине слова:
un*frigging*believable
Но если окружить символ * или _ пробелами, то он будет рассматриваться как буквальная звездочка или подчеркивание.
Чтобы создать буквальную звездочку или подчеркивание в том месте, где они в противном случае использовались бы в качестве разделителя акцента, то можно сделать это, экранировав данный символ обратной косой чертой \:
\*this text is surrounded by literal asterisks\*
Для обозначения исходного кода программы или какого-либо языка разметки, в документах Markdown используется предварительно отформатированные блоки. Вместо того чтобы формировать обычные абзацы, строки блоков с кодом интерпретируются буквально. Markdown оборачивает блок кода в оба тега <pre> и <code>.
Чтобы создать блок кода в документе Markdown, просто сделайте отступ в каждой строке блока не менее чем на 4 пробела или 1 табуляцию. Например:
This is a normal paragraph:
This is a code block.
Markdown будет генерировать:
<p>This is a normal paragraph:</p> <pre><code>This is a code block. </code></pre>
Один уровень отступа - 4 пробела или 1 табуляция, удаляется из каждой строки блока с кодом. Например:
Here is an example of AppleScript:
tell application "Foo"
beep
end tell
превратится в:
<p>Here is an example of AppleScript:</p> <pre><code>tell application "Foo" beep end tell </code></pre>
Блок кода продолжается до тех пор, пока он не достигнет строки без отступа (или конца статьи).
Внутри блока с кодом амперсанды & и угловые скобки < и > автоматически преобразуются в HTML-сущности. Такое поведение позволяет очень легко включить пример исходного кода HTML с помощью разметки Markdown - просто вставьте его и сделайте отступ, остальное движок Markdown сделает сам. Например:
` <div class="footer">
© 2004 Foo Corporation
</div>
превратится в:
<pre><code><div class="footer"> &copy; 2004 Foo Corporation </div> </code></pre>
Обратите внимание, внутри блоков с кодом, синтаксис Markdown не обрабатывается, например, звездочки - это просто буквальные звездочки.
Чтобы указать строку с кодом в тексте, оберните его обратными кавычками `. В отличие от предварительно отформатированного блока кода, строку с кодом указывает код в пределах обычного абзаца. Например:
Use the `printf()` function.
будет генерировать следующее:
<p>Use the <code>printf()</code> function.</p>
Чтобы включить символ обратной кавычки в строку с кодом, можно использовать несколько символов обратных кавычек в качестве разделителей открытия и закрытия:
``There is a literal backtick (`) here.``
будет генерировать следующее:
<p><code>There is a literal backtick (`) here.</code></p>
Обратные кавычки, окружающие строку с кодом, могут включать пробелы - один после открытия, один перед закрытием. Это позволяет размещать символы обратных кавычек в начале или конце строки с кодом:
A single backtick in a code span: `` ` `` A backtick-delimited string in a code span: `` `foo` ``
будет генерировать следующее:
<p>A single backtick in a code span: <code>`</code></p> <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
При использовании строк кода амперсанды & и угловые скобки < и > автоматически кодируются как HTML-сущности, что позволяет легко включать примеры HTML-тегов:
Please don't use any `<blink>` tags.
преобразует в:
<p>Please don't use any <code><blink></code> tags.</p>
Так же можно написать следующее:
`—` is the decimal-encoded equivalent of `—`.
в итоге получится:
<p><code>&#8212;</code> is the decimal-encoded equivalent of <code>&mdash;</code>.</p>
<hr>.Можно создать горизонтальный тег <hr />, поместив три или более дефиса -, звездочки * или подчеркивания _ в отдельную строку. При желании, можно использовать пробелы между дефисами или звездочками. Каждая из следующих строк, в последствии создаст HTML-тег <hr />:
* * * *** ***** - - - ---------------------------------------
<a>.Markdown поддерживает два стиля ссылок: inline и reference.
В обоих стилях текст ссылки разделен [квадратными скобками].
Чтобы создать встроенную inline ссылку, необходимо использовать набор обычных круглых скобок сразу после закрывающей квадратной скобки текста ссылки. В круглых скобках укажите URL-адрес, на который должна указывать ссылка, а также необязательный заголовок title ссылки, заключенный в кавычки. Например:
This is [an example](http://example.com/ "Title") inline link. [This link](http://example.net/) has no title attribute.
Будет генерировать следующий HTML:
<p>This is <a href="http://example.com/" title="Title"> an example</a> inline link.</p> <p><a href="http://example.net/">This link</a> has no title attribute.</p>
Если ссылка ведет на локальный ресурс на том же сервере, то можно использовать относительные пути:
See my [About](/about/) page for details.
Ссылки в стиле reference используют второй набор квадратных скобок, внутри которых помещается метка по выбору пользователя для идентификации ссылки:
This is [an example][id] reference-style link.
Можно дополнительно использовать пробел для разделения наборов скобок:
This is [an example] [id] reference-style link.
Затем, в любом месте документа, на отдельной строке определяется метка ссылки:
[id]: http://example.com/ "Optional Title Here"
Алгоритм создания метки ссылки, при создании ссылок в стиле reference:
Следующие три определения ссылок эквивалентны:
` [foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Optional Title Here'
[foo]: http://example.com/ (Optional Title Here)
URL-адрес ссылки может быть дополнительно заключен в угловые скобки:
[id]: <http://example.com/> "Optional Title Here"
Можно поместить атрибут title в следующую строку и использовать дополнительные пробелы или табуляции для заполнения, что, как правило, выглядит лучше при более длинных URL-адресах:
[id]: http://example.com/longish/path/to/resource/here "Optional Title Here"
Определения ссылок используются только для создания ссылок во время обработки Markdown и удаляются из вашего документа в выводе HTML.
Имена определений ссылок могут состоять из букв, цифр, пробелов и знаков препинания, они так же нечувствительны к регистру:
[link text][a] эквивалентно [link text][A]
Ярлык неявного имени ссылки позволяет опустить имя ссылки, и в этом случае в качестве имени используется сам текст ссылки. Для такого поведения, просто, используйте пустой набор квадратных скобок - например, чтобы связать метку со словом "Google" с сайтом google.com, можно написать:
[Google][]
А затем проставьте метку, определив связь:
[Google]: http://google.com/
Поскольку имена ссылок могут содержать пробелы, то следующий ярлык будет работать даже для нескольких слов в тексте ссылки:
Visit [Daring Fireball][] for more information.
А затем определите связь:
[Daring Fireball]: http://daringfireball.net/
Определения ссылок могут быть размещены в любом месте документа Markdown. Хорошей практикой считается помещать их сразу после каждого абзаца, в котором они используются, но если необходимо, то можно поместить их все в конце документа, что-то вроде сносок.
Вот пример ссылок в действии:
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"
Оба вышеприведенных примера приведут к следующему выводу HTML:
<p>I get 10 times more traffic from <a href="http://google.com/" title="Google">Google</a> than from <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
Для сравнения, вот тот же самый абзац, написанный с использованием встроенного inline стиля ссылок Markdown:
I get 10 times more traffic from [Google](http://google.com/ "Google") than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or [MSN](http://search.msn.com/ "MSN Search").
Смысл ссылок reference стиля не в том, что их легче писать. Дело в том, что с reference ссылками ваш источник документа значительно более удобочитаем. Сравните приведенные выше примеры: при использовании ссылок reference стиля сам абзац имеет длину всего 81 символ, а при использовании ссылок inline стиля - 176 символов, а в виде необработанного HTML-кода - 234 символа.
С reference ссылками, исходный документ Markdown больше напоминает конечный результат, отображаемый в браузере.
<img>.Довольно сложно разработать “естественный” синтаксис для размещения изображений в формате обычного текстового документа.
Разметка Markdown использует синтаксис публикации изображений, напоминающий синтаксис размещения ссылок, так же используя два стиля: inline и reference.
Размещение изображения в документе inline стилем выглядит следующим образом:
 
Алгоритм публикации изображения в документе inline стилем:
!;alt);Синтаксис изображения в reference стиле выглядит следующим образом:
![Alt text][id]
Где id - это имя метки изображения, которая может определятся в любом месте документа. Другими словами, метки на изображения определяются с использованием синтаксиса идентичного ссылкам:
[id]: url/to/image "Optional title attribute"
У разметки Markdown нет синтаксиса для указания размера изображения, если это важно, то необходимо использовать обычные HTML-теги <img>.
Markdown поддерживает стиль быстрого создания “автоматических” ссылок для URL-адресов и адресов электронной почты. Для этого окружите URL-адрес или адрес электронной почты угловыми скобками < и >. Такое поведение означает, что если в документе Markdown допустимо показать фактический URL или адрес электронной почты, а также сделать его кликабельной ссылкой, то можно сделать следующее:
<http://example.com/>
Markdown преобразует это в:
<a href="http://example.com/">http://example.com/</a>
Автоматические ссылки для адресов электронной почты работают аналогично, за исключением того, что Markdown также выполнит скрытие фактического адреса от спам-ботов. Например:
<address@example.com>
закодирует адрес электронной почты в нечто подобное:
<a href="mailto:addre ss@example.co m">address@exa mple.com</a>
который будет отображаться в браузере в виде кликабельной ссылки на “address@example.com".
Этот трюк с кодированием сущностей действительно обманет многих, если не большинство, ботов по сбору адресов E-Mail, но он определенно не обманет их всех. Это лучше, чем ничего, но адрес, опубликованный таким образом , вероятно, в конечном итоге начнет получать спам.
Markdown позволяет использовать обратные слешы \ для создания буквенных символов, которые в противном случае имели бы особое значение в синтаксисе форматирования Markdown. Например, если надо окружить слово буквальными звездочками (вместо HTML-тега <em>), можно использовать обратный слеш перед звездочками, например так:
\*literal asterisks\*
Markdown предоставляет экранирование обратной косой черты для следующих символов:
\ - обратный слэш,` - обратная кавычка,* - звездочка,_ - подчеркивание,{} - фигурные скобки,[] - квадратные скобки,() - скобка,# - хэш-метка,+ - знак плюс,- - знак минус (дефис),. - точка,! - exclamation mark.