Markdown

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

Автором языка Markdown является John Gruber; он упоминает, что Aaron Swartz весьма помог идеями и тестированием, а ещё заслуживают благодарности Nathaniel Irons, и Dan Benjamin, и Daniel Bogan, и Jason Perkins.

Модуль преобразования разметки из Markdown в HTML написан Грубером на языке Perl и распространяется по BSD-подобной лицензии; благодаря такой открытости кода этот модуль входит в дистрибутив или доступен как расширение во многих системах управления содержанием и движках блогов. Markdown был портирован с языка Perl на многие другие языки; следует особенно отметить порт «PHP Markdown Extra», автором которого является Michel Fortin, поскольку «PHP Markdown Extra» пополняет синтаксис Markdown несколькими дополнительными (и весьма полезными) функциями.

Синтаксис Markdown

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

Вставка HTML

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

Единственное ограничение состоит в том, что блочные элементы HTML (то есть <div>, <table>, <pre>, <p> и т. п.) должны отделяться пустыми строками от окружающего их текста, причём начальный и конечный тэг не должны отступать от начала строки. Markdown достаточно сметлив, чтоб не вставлять дополнительные (нежелательные) элементы <p> вокруг блочных элементов HTML.

Вот пример вставки HTML-таблицы в статью, написанную на Markdown:

Это обычный абзац.

<table>
  <tr>
    <td>Это ячейка таблицы.</td>
  </tr>
</table>

Это следующий обычный абзац.

Синтаксис форматирования Markdown не обрабатывается внутри блочных элементов HTML. Например, нельзя использовать маркдауновское *выделение текста* (см. ниже) внутри блока HTML.

Внутристрочные тэги HTML (то есть <span>, <cite>, <del> и т. п.) могут использоваться где угодно внутри маркдауновских абзацев, элементов списков, в заголовках. Если угодно, тэги HTML можно использовать вместо маркдауновского форматирования: например, если автор текста предпочитает HTMLовские элементы <a> или <img> маркдауновскому синтаксису гиперссылок и изображений соответственно, то может пользоваться ими, и тем невозбранно достигнуть желаемого.

В отличие от блочных элементов HTML, во внутристрочных элементах HTML обрабатывается синтаксис Markdown.

Автоматическое кодирование специальных символов

В языке HTML есть два символа, требующих специального к себе отношения: это < и &. Левая угловая скобка используется как начало тэга; амперсанды применяются для обозначения сущностей (entities). А чтобы использовать эти символы в их буквальном смысле, приходится их самих приводить как сущности, то есть < и & соответственно.

Амперсанды в особенности сбивают с толку авторов, пишущих для WWW. Скажем, чтобы написать про AT&T, приходится писать «AT&amp;T». Приходится избавляться от амперсандов и в URLах. Таким образом, если надобно сослаться на URL вида

http://images.google.com/images?num=30&q=larry+bird

то в атрибуте href его надобно кодировать так:

http://images.google.com/images?num=30&q=larry+bird

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

Markdown позволяет использовать эти символы естественным образом; он сам заботится о том, как их необходимо избегать. Если амперсанд используется как часть HTML-сущности, то он останется неизменным; в противном случае Markdown превратит его в &.

Таким образом, чтобы вставить символ копирайта в статью, достаточно написать

©

и Markdown оставит его как есть. А если написать

AT&T

то Markdown преобразует его в код

AT&T

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

4 < 5

то Markdown преобразует этот текст в код

4 < 5

Однако внутри кодовых фрагментов строк и кодовых блоков Markdown угловые скобки и амперсанды всегда кодируются автоматически. Это упрощает использование Markdown в случае, когда текст посвящён языку HTML, и выгодно отличает Markdown от самого́ языка HTML (на котором ужасно неудобно писать о синтаксисе HTML, поскольку символов < или & приходится избегать посредством специального кодирования).

Блочные элементы разметки

Абзацы и переводы строки

Абзац записывается в Markdown весьма просто: это одна или несколько строк текста, отделённые от окружающего текста одной (или более чем одной) пустой строкою. (Пустой строкою считается всякая, которая выглядит пустой; строка, не содержащая ничего, кроме пробелов и символов табуляции, считается пустой.) Обычные параграфы не следует снабжать отступом из пробелов или символов табуляции.

Следствием правила «одна или несколько строк текста» является поддержка Маркдауном таких абзацев текста, в которых имеются «жёсткие переводы строки» (то есть такие места́, в которых автор нажимал на кнопку «ввод», также называемую «Enter»). Это заметно отличает Markdown от большинства других средств преобразования текста в HTML (например, от Movable Type с включённой настройкою «Convert Line Breaks»), поскольку эти средства преобразуют переводы строк в HTML-элемент <br /> — и, стало быть, прерывают им обычное течение текста в абзаце.

Чтобы вставить видимый перенос строки (элемент <br />) посредством Markdown, надобно окончить строку двумя (или более) пробелами, и только затем нажать на «ввод» («Enter»).

Безусловно, это требует несколько больших усилий, нежели простое правило «каждый перевод строки преобразуется в <br /> и становится видимым», однако такое правило для Markdown не подходит. Некоторые (рассматриваемые далее) особенности синтаксиса Markdown — email-подобное блочное цитирование, многоабзацные элементы списков — гораздо лучше выглядят и работают, если их форматировать «жёсткими переводами строки».

Заголовки

Markdown поддерживает два стиля заголовков: подчёркнутые и выделенные символом «#».

Подчёркнутые заголовки подчёркиваются знаками равенства (если заголовок первого уровня) или дефисами (если второго уровня). Вот пример:

Заголовок первого уровня (соответствует H1 в HTML)
==================================================

Заголовок второго уровня, H2
----------------------------

Годится какое угодно количество подчёркивающих символов «=» или «-».

Заголовки, выделенные символом «#», используют от одного до шести таких символов подряд в начале строки; количество символов соответствует уровню заголовка (от первого до шестого). Вот пример:

# Заголовок первого уровня

## Заголовок второго уровня

###### Заголовок шестого уровня (H6)

При желании можно снабжать эти заголовки «закрывающими» символами «#». (Это не обязательно, но вполне возможно, если автор текста полагает, что с «закрывающими» символами «#» заголовок выглядит красивее.) Количество таких конечных символов не обязано соответствовать количеству начальных символов. Уровень заголовка определяется только количеством начальных символов «#»:

# Заголовок первого уровня #

## Заголовок второго уровня ##

### Заголовок третьего уровня ######

Блоки цитат

Markdown использует email-подобный стиль использования символов > для оформления цитат. Поэтому тем авторам, которым привычна электронная почта, уже́ известен и маркдауновский способ создания цитат. Лучше всего цитата выглядит, если оформить её «жёсткими переводами строки» (см. выше), и каждую строку начать символом «>»:

> Это цитата, состоящая из двух абзацев текста. Вы видите, что первый
> абзац состоит из нескольких строк, каждой из которых предшествует
> символ закрывающей угловой скобки.
> 
> Это второй абзац текста. Обратите внимание на то, что символом
> цитирования снабжён также и промежуток между абзацами.

Markdown снисходителен к лентяям, и оттого позволяет ставить > только перед первой строкой абзаца, даже когда «жёсткими переводами строки» он разбит на несколько строк.

> Это цитата, состоящая из двух абзацев текста. Вы видите, что первый
абзац состоит из нескольких строк, но только первой из них предшествует
символ закрывающей угловой скобки.

> Это второй абзац текста.

Цитаты могут быть вложенными (то есть цитатами внутри цитат), для их разметки используются дополнительные уровни «>»:

> Это первый уровень цитирования.
>
> > Это вложенная цитата.
>
> Возвращаемся на первый уровень цитирования.

Цитаты могут содержать и другие элементы Markdown — заголовки, списки, кодовые блоки:

> ## Это заголовок.
> 
> 1.   Это первый элемент нумерованного списка.
> 2.   Это второй элемент нумерованного списка.
> 
> Вот пример кода:
> 
>     return shell_exec("echo $input | $markdown_script");

Многие текстовые редакторы понимают email-подобный стиль цитирования, способны применять его к выделенному пользователем тексту, увеличивать и уменьшать уровень вложенности цитаты; это обстоятельство делает такие редакторы (например, BBEdit) полезными при работе с цитатами в Markdown.

Списки

Markdown позволяет составлять нумерованные и ненумерованные списки.

В качестве маркеров ненумерованного списка используются звёздочки, или плюсы, или дефисы; эти символы могут для этой цели использоваться взаимозаменяемо. Скажем, вот этот пример:

*   Красный
*   Зелёный
*   Синий

совершенно равносилен вот этому:

+   Красный
+   Зелёный
+   Синий

или вот этому:

-   Красный
-   Зелёный
-   Синий

Нумерованные списки используют в качестве маркеров числа с точкою:

1.  Чкалов
2.  Байдуков
3.  Беляков

Конкретные числа, которые используются при разметке списка, не оказывают никакого влияния на производящийся Маркдауном итоговый HTML-код. По вышеприведённому списку Markdown изготовит такой HTML-код:

<ol>
<li>Чкалов</li>
<li>Байдуков</li>
<li>Беляков</li>
</ol>

Если вместо этого записать список так:

1.  Чкалов
1.  Байдуков
1.  Беляков

или даже так:

1. Чкалов
8. Байдуков
3. Беляков

то получится совершенно тот же HTML-код. Смысл в том, что при желании автор может использовать порядковые номера элементов в списке, чтобы они соответствовали номерам, получающимся в HTML. Но также автор может и не тратить на это своё время, если это не особенно для него важно.

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

Маркеры списков обычно начинаются с начала строки, но им могут предшествовать до трёх пробелов. За маркером должен следовать либо пробел (один или более), либо символ табуляции.

Для красоты можно снабжать последующие строки списка отступами:

*   Это первый элемент списка. Он содержит жёсткие переносы строк,
    и в начале каждой строки находится отступ, соответствующий
    началу текста после маркера, расположенного в первой строке.
*   Это второй элемент списка. Он оформлен сходным образом:
    в начале каждой строки его находится отступ, соответствующий
    началу текста после маркера, расположенного в первой строке.

Но если нет надобности, то на это можно не тратить время:

*   Это первый элемент списка. Достаточно поставить маркер списка
в начале первой строки его, и все остальные строки можно начинать
от левого края без отступа.
*   Это второй элемент списка. Он оформлен сходным образом:
в начале первой строки его находится маркер, а остальные строки
следуют за нею безо всякого дополнительного отступа.

Если элементы списка разделяются пустыми строками, то Markdown обернёт эти элементы тэгами <p> в своём итоговом HTML-коде. Скажем, вот этот список:

*   Святослав
*   Владимир

будет преобразован к виду

<ul>
<li>Святослав</li>
<li>Владимир</li>
</ul>

а зато вот этот:

*   Святослав

*   Владимир

будет преобразован к виду

<ul>
<li><p>Святослав</p></li>
<li><p>Владимир</p></li>
</ul>

Элементы списка могут состоять из нескольких абзацев. Второй, и третий, и каждый последующий абзац элемента должны снабжаться отступом из четырёх пробелов или одного символа табуляции:

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

    Это второй абзац первого элемента. Обратите внимание
    на отступ перед его первой строкою.

2.  Это второй элемент списка.

Список выглядит красиво, если отступом снабжать каждую строку. Но если нет времени этим заниматься, то для Markdown достаточно снабдить им только первую строку абзаца:

1.  Это элемент списка, состоящий из двух абзацев. И хотя
не все строки абзацев не снабжаются отступами, Markdown всё же
способен понять, что второй абзац является частью списка.

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

2.  Это второй элемент списка.

Если внутри элемента списка располагается цитата, то надобно снабжать отступом разделители «>», цитате предшествующие:

*   Этот элемент списка содержит цитату:

    > Вот эта цитата, содержащаяся
    > внутри элемента списка.

Чтобы поместить кодовый блок внутри элемента списка, этот кодовый блок надобно снабдить двукратным отступом, то есть либо восемью пробелами, либо двумя символами табуляции:

*   Этот элемент списка содержит кодовый блок:

        первая строка кода;
        вторая строка кода;
        ...

К сожалению, нумерованный список можно начать случайно, просто написав что-нибудь в таком духе:

1978. Эх, какой счастливый год выдался!..

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

1978\. Эх, какой счастливый год выдался!..

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

Блоки кода

Блоки отформатированного кода приводятся в статьях о программировании или о разметке текста, когда возникает надобность процитировать исходники. В отличие от обычных абзацев, переносы строк в кодовом блоке воспринимаются буквально. Markdown обрамляет кодовый блок сразу двумя элементами HTML — и <pre>, и <code>.

Чтобы создать блок кода в Markdown, достаточно просто снабдить каждую строку блока отступом, состоящим из четырёх пробелов или одного символа табуляции. Например, вот этот текст:

Это обычный абзац.

    А это кодовый блок.

будет преобразован Маркдауном в следующий HTML-код:

<p>Это обычный абзац.</p>

<pre><code>А это кодовый блок.
</code></pre>

Один уровень отступа (4 пробела или 1 символ табуляции) устраняются из каждой строки кодового блока. Например, вот этот текст:

Это пример на языке AppleScript:

    tell application "Foo"
        beep
    end tell

будет преобразован к виду

<p>Это пример на языке AppleScript:</p>

<pre><code>tell application "Foo"
    beep
end tell
</code></pre>

Блок кода продолжается до тех пор, покуда не отыщется строка без отступа (или конец текста).

Внутри кодового блока амперсанды («&») и угловые скобки («<» и «>») автоматически преобразуются в HTML-сущности (HTML entities). Поэтому нетрудно использовать Markdown для включения примеров на языке HTML: достаточно вставить их и снабдить отступом, а Markdown позаботится о кодировании амперсандов и угловых скобок. Скажем, вот этот пример:

    <div class="footer">
        &copy; 2004 Foo Corporation
    </div>

примет вид следующего HTML-кода:

<code>&lt;div class="footer"&gt;
    &amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code>

Обычный синтаксис Markdown не обрабатывается внутри блоков кода. Например, звёздочки внутри кодового блока считаются просто звёздочками в буквальном смысле. Так что нетрудно использовать Markdown, чтобы на нём писать о его собственном синтаксисе, приводя наглядные примеры.

Горизонтальная черта

Чтобы создать горизонтальную черту (соответствующую HTML-элементу <hr />), достаточно поместить три (или более) дефиса, или звёздочки, или символа подчёркивания, на отдельной строке текста. Если угодно, между дефисами или звёздочками можно располагать пробелы. Каждая из следующих строк соответствует горизонтальной черте:

* * *

***

*****

- - -

---------------------------------------

Внутристрочные элементы разметки

Гиперссылки

Markdown поддерживает три стиля оформления гиперссылок:

• с немедленным указанием адреса;
• подобные сно́скам,
• простую вставку URL.

Первая пара стилей предполагает, что помимо URLа существует ещё текст ссылки; в разметке он [заключается в квадратные скобки].

Гиперссылка с немедленным указанием адреса

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

Это [пример](http://example.com/ "заголовок") ссылки с немедленным указанием адреса.
Эта ссылка снабжена всплывающим заголовком-подсказкою.

[А для этой ссылки](http://example.net/) заголовок не указан.

Из этого примера выйдет следующий HTML-код:

<p>Это <a href="http://example.com/" title="заголовок">
пример</a> ссылки с немедленным указанием адреса.
Эта ссылка снабжена всплывающим заголовком-подсказкою.</p>

<p><a href="http://example.net/">А для этой ссылки</a> заголовок не указан.</p>

Для ссылок на локальный ресурс (то есть расположенный на том же сервере) можно использовать относительные пути:

Подробности приводятся на странице [About.](/about/)

Гиперссылка, подобная сноске

Ссылка, подобная сноске, вместо целевого адреса использует вторую пару квадратных скобок, внутри которых помещается метка, идентификатор ссылки:

Это [пример][id] ссылки, подобной сноске.

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

Это [пример] [id] ссылки, подобной сноске.

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

[id]: http://example.com/  "А здесь необязательный заголовок ссылки"

Строка эта состоит из следующих элементов:

• Идентификатор ссылки, окружённый квадратными скобками (которым может предшествовать необязательный отступ — от одного до трёх пробелов).
• Двоеточие,
• Один или несколько пробелов (или символов табуляции).
• URL гиперссылки.
• Необязательный заголовок (всплывающая подсказка) гиперссылки, заключённый либо в двойные или одиночные кавычки, либо в скобки.

Три следующие определения ссылки совершенно равносильны:

[foo]: http://example.com/  "А здесь необязательный заголовок"
[foo]: http://example.com/  'А здесь необязательный заголовок'
[foo]: http://example.com/  (А здесь необязательный заголовок)

URL гиперссылки может (но не обязательно) быть помещён в угловые кавычки:

[id]: <http://example.com/>  "А здесь необязательный заголовок"

Можно поместить заголовок на следующей строке, а перед ним отступ из пробелов (или символов табуляции); с длинными URL такая запись выглядит красивее:

[id]: http://example.com/longish/path/to/resource/here
      "А здесь необязательный заголовок"

Такие определения ссылок используются только для создания самих ссылок при обрабоке текста в Markdown; из итогового HTML-кода определения ссылок убираются.

Идентификаторы ссылок могут состоять из букв, цифр, пробелов и знаков пунктуации, однако они не чувствительны к регистру. Например, вот эти две ссылки:

[link text][a]
[link text][A]

совершенно равносильны.

Markdown позволяет также использовать подразумеваемый ярлык гиперссылки; в этом случае метка не приводится, вместо неё текст гиперссылки используется и в качестве её имени, а вторая пара квадратных скобок остаётся пустою. Например, чтобы сделать слово «Google» гиперссылкой, ведущей на сайт google.com, достаточно написать:

[Google][]

и затем определить гиперссылку:

[Google]: http://google.com/

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

На сайте [Daring Fireball][] располагается описание Markdown.

А затем определите гиперссылку:

[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>

Для сравнения, вот тот же абзац, записанный в 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").

Смысл ссылок, подобных сноскам, не в том, что их проще записывать. Смысл в том, что с такими ссылками сам абзац занимает 81 символов, в то время как с немедленным указанием адреса он занял бы 176 символов, а в HTML занимает 234 символа. Таким образом, в HTML разметка занимает даже больше места, чем сам текст.

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

Простая вставка URL

Markdown поддерживает упрощённый порядок автоматического создания ссылок для URLов и адресов электронной почты: достаточно поместить URL или почтовый адрес в угловые скобки, и Markdown сделает его гиперссылкою. В отличие от вышеописанных стилей, в данном случае сам же URL или почтовый адрес становится и текстом гиперссылки. Скажем, если надобно опубликовать некоторый URL, и одновременно сделать его гиперссылкою, то достаточно написать

<http://example.com/>

и Markdown сделает из него HTML-код

<a href="http://example.com/">http://example.com/</a>

Автоматические ссылки на адреса электронной почты работают аналогично, но над ними Markdown дополнительно совершает псевдослучайные операции десятичного и шестнадцатиричного сущностного кодирования (entity-encoding), чтобы скрыть адрес от автоматических сборщиков почты, которыми пользуются спамеры. Например, вот такой адрес:

<[email protected]>

преобразуется к такому примерно виду:

<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>

который браузером отображается как ссылка, ведущая на «[email protected]».

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

Markdown воспринимает звёздочки («*») и символы подчёркивания («_») как признаки смыслового выделения текста:

• Текст, окружённый одиночными «*» или «_», обёртывается в HTML-тэг <em>.
• Текст, окружённый двойными «*» или «_», обёртывается в HTML-тэг <strong>.

Например, вот этот текст:

*одиночные звёздочки*

_одиночные символы подчёркивания_

**двойные звёздочки**

__двойные символы подчёркивания__

будет преобразован в следующий HTML-код:

<em>одиночные звёздочки</em>

<em>одиночные символы подчёркивания</em>

<strong>двойные звёздочки</strong>

<strong>двойные символы подчёркивания</strong>

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

Выделенный фрагмент может находиться и в середине слова:

un*fucking*believable

Но если символ «*» или «_» окружён пробелами, он приобретает своё буквальное значение.

Чтобы получить звёздочку или символ подчёркивания в той позиции, в которой этот символ в противном случае мог бы быть воспринят как выделение текста, надобно поставить обратную косую черту перед звёздочкою или знаком подчёркивания:

\*звёздочки вокруг этого текста воспринимаются буквально\*

Кодовые фрагменты строк

Чтобы отметить фрагмент строки, содержащий код, надобно окружить его обратными апострофами («`»). В отличие от блоков кода, кодовый фрагмент позволяет поместить код внутрь обычного абзаца текста. Вот пример:

Используйте функцию `printf()` для вывода текста.

Он соответствует следующему HTML-коду:

<p>Используйте функцию <code>printf()</code> для вывода текста.</p>

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

``Обратный апостроф (`) будет воспринят здесь буквально.``

HTML-код получится таким:

<p><code>Обратный апостроф (`) будет воспринят здесь буквально.</code></p>

Обратные апострофы, окружающие код, могут содержать пробелы — один пробел после открывающих апострофов, а один после закрывающих. Это позволяет поместить обратный апостроф (в его буквальном значении) в самом начале и (или) в самом конце кодового фрагмента строки. Вот примеры:

Обратный апостроф в кодовом фрагменте: `` ` ``

Обрамлённая обратными апострофами строка в кодовом фрагменте: `` `foo` ``

HTML-код этого примера получится таким:

<p>Обратный апостроф в кодовом фрагменте: <code>`</code></p>

<p>Обрамлённая обратными апострофами строка в кодовом фрагменте: <code>`foo`</code></p>

Внутри кодового фрамента строки все амперсанды и угловые скобки преобразуются к виду соответствующих HTML-сущностей (HTML entities), что упрощает включение примеров на языке HTML. Например, Markdown преобразует вот этот текст:

Пожалуйста, не используйте элементы `<blink>`.

к следующему HTML-виду:

<p>Пожалуйста, не используйте элементы <code>&lt;blink&gt;</code>.</p>

Можено также написать:

`—` является десятично-кодированным эквивалентом `—`.

и получить следующий HTML-код:

<p><code>&amp;#8212;</code> является десятично-кодированным
эквивалентом <code>&amp;mdash;</code>.</p>

Изображения

Спору нет, не так-то просто разработать более или менее «естественный» синтаксис для помещения изображений в текстовый документ. Markdown для помещения изображений пользуется синтаксисом, подобным собственному же маркдауновскому синтаксису гиперссылок. Подобно гиперссылкам, разметка изображения в Markdown может либо непосредственно указывать URL, либо (подобно сноске) содержать метку-идентификатор.

Синтаксис непосредственного указания URL изображения таков:

![Альтернативный текст](/путь/к/изображению.jpg)

или таков:

![Альтернативный текст](/путь/к/изображению.jpg "Необязательное заглавие")

Иными словами, он состоит из следующих элементов:

• Восклицательный знак.

• Квадратные скобки, в которых указывается альтернативный изображению текст (он станет содержимым атрибута alt в элементе img).

• Круглые скобки, содержащие URL или относительный путь изображения, а также (необязательно) содержимое атрибута title (всплывающей подсказки к изображению), заключённое в двойные или одиночные кавычки.

Изображения в подобной сноскам манере записываются следующим образом:

![Альтернативный текст][id]

где «id» — имя определённой метки изображения. Метки изображений определяются при помощи синтаксиса, совершенно идентичного меткам гиперссылок:

[id]: путь/к/изображению  "Необязательный title"

Следует отметить, что Markdown не позволяет задать размеры изображения (ширину, высоту); если же такое задание важно, то следует использовать обычный элемент <img> языка HTML.

Употребление обратной косой черты

Как уж было сказано выше, обратная косая черта (символ «\») может употребляться в Markdown перед специальными символами для того, чтобы они воспринимались в их буквальном (а не служебном) значении. Например, если надобно поместить текст в обрамлении звёздочек (а не использовать звёздочки как символ смыслового выделения текста), то можно записать его так:

\*текст между двух звёздочек\*

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

\	обратная косая черта
`	обратный апостроф
*	звёздочка
_	символ подчёркивания
{ }	фигурные скобки
[ ]	квадратные скобки
( )	круглые скобки
#	решётка
+	плюс
-	минус (дефис)
.	точка
!	восклицательный знак

Синтаксис PHP Markdown Extra

PHP Markdown Extra — это специальная версия Markdown, реализующая некоторые особенности синтаксиса, отсутствующие в обычном Markdown. Эта версия, реализованная на языке PHP, может быть скачана с домашней страницы PHP Markdown.

Этот раздел статьи описывает изменения и дополнения, внесённые в синтаксис Markdown программою PHP Markdown Extra.

См. также

• Markdown в Английской Википедии

Ссылки

• Официальный сайт
• Русский перевод официальной документации по Markdown