Справка по Markdown - форматированию

Общие вопросы

Примечание

Устарело в связи с переходом на новую систему

Включение HTML

Markdown - форматирование создано для удобства письма во всемирной паутине и ни в коем случае не является заменой HTML. Так что он позволяет при редактировании включать в текст блоки HTML кода, которые останутся неизменными при обработке.

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

В HTML существуют два символа заслуживающих отдельного рассмотрения: < и &. Левые угловые скобки используются для обозначения начала тэгов; амперсанды используются для обозначения элементов HTML. Если вы хотите их использовать, вам следует заменить их элементами HTML т.е. &lt и &amp

Markdown позволяет не думать об этом и сам заменяет их на нужные. Т.е. если вы будете употреблять при написании элементы языка то он не бует их изменять. Но стоит вам написать "AT&T" тотчас амперсанд будет заменен на &.

Например, если вы хотите включить символ копирайта в ваш текст, то просто напишите:

&copy

и Markdown ничего не тронет. Но если вы напишете:

AT&T

Markdown превратит это в:

 AT&T 

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

4 < 5

Markdown приведет это к виду:

4 < 5

Несмотря на это в блоках кода и "строковом" коде Markdown-а угловые скобки и амперсанды всегда автоматически преобразуются. Это делает Markdown удобным средством для того чтобы писать о HTML коде. (В противовес обычному HTML, который является ужасным форматом, для написания чего-либо о синтаксисе HTML, потому что каждый символ < и & в примерах кода должен быть заменен)

Блоковые элементы

Параграфы и разрывы строк

Параграф - это одна или несколько последовательных строк текста отделенных одной или несколькими пустыми строками. (Пустой строкой считается то что выглядит как пустая строка – строка содержащая ничего другого кроме пробелов и табуляций.) Обычные параграфы не должны быть отформатированы с использованием пробелов или табуляций.

Заголовки

Markdown поддерживает 2 стиля форматирования заголовков, Setext и atx Заголовки setext-стиля "подчеркиваются" с помощью знаков равно (для заголовков первого уровня) и чертами "тире" (для заголовков второго уровня). Например:

Это заголовок первого уровня
======================

А это - второго
------------

Любое количество "подчеркивающих" символов '=' или '-' будет обработано верно.

В заголовках atx-стиля используются от 1 до 6 символов # в начале строки, в соответствии с заголовками 1-6 уровней. Например:

# Это заголовок первого уровня
## Это - второго
###### А это - шестого

По вашему усмотрению вы можете "закрывать" заголовки стиля atx, используя один или несколько символов # в конце строки. Это помогает сделать текст в редакторе более приятным для взгляда, но, на самом деле не привносит ровно ничего. Число "закрывающих" символов даже может не соответствовать числу "открывающих". (При этом количество "открывающих" символов указывает на уровень заголовка.) :

# Это заголовок первого уровня #
## Это - второго ##
### А это - третьего ######

Цитаты

В Markdown используются символы "больше" ( > ) для обозначений цитат. Они пришли в него из электронной почты, так что если вы можете вставить цитату в письмо, то вы сможете сделать это и в 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.

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.

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

> Это первый уровень цитирования.
>> Это вложенная цитата.
>
> Опять первый уровень

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

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

Списки

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

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

все равно что:

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

и:

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

Упорядоченные списки формируются с помощью комбинации "номер." (как показано ниже):

1. Птица
2. RomanKondakov
3. Парик

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

<ol>
<li>Птица</li>
<li>RomanKondakov</li>
<li>Парик</li>
</ol>

Если бы вы сформировали список так:

1. Птица
1. RomanKondakov
1. Парик

или даже так:

3. Птица
1. RomanKondakov
8. Парик

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

Первое правило относящееся к упорядоченным спискам – при форматировании их следует начинать с " 1. ".

Второе - обычно обозначения списка ставятся у левого края и они могут быть отодвинуты не больше чем на 3 пробела. Сразу после обозначения, должны стоять один или несколько пробелов или табуляция.

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

* 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. Например вот этот список:

* Птица
* Магия

Превратится:

<ul>
<li>Птица </li>
<li>Магия</li>
</ul>

Но этот:

* Птица

* Магия

превратится в:

<ul>
<li><p>Птица</p></li>
<li><p>Магия</p></li>
</ul>

Элементы списка могут состоять из нескольких параграфов. Каждый следующий параграф должен быть сформирован с отступом в 4 пробела или одну табуляцию:

 1. Это элемент списка с двумя параграфами. 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.

Если сделать одинаковый отступ для всех строк элемента, он выглядит намного лучше. Но тут вновь Markdown позволяет полениться:

 *  Это элемент списка с двумя параграфами.

    Это второй параграф элемента. С отступа нужно начинать
только первую строку. Lorem ipsum dolor sit amet, consectetuer
adipiscing elit.

 *  Еще один элемент того же списка.

Если вы хотите вставить цитату в список, то все обозначения цитирования ( > ) нужно писать с отступом:

 * Элемент списка с цитатой:
 > Это цитата
 > внутри элемента списка.

Для того чтобы вставить исходный код в элемент списка, его нужно писать с двойным отступом — 8 пробелов или 2 табуляции:

* Элемент списка с куском исходного кода:

        <код будет здесь>

Ничего не стоит случайно создать список, написав что-то вроде:

1986. Какой прекрасный год.

Другими словами, последовательность номер-точка-пробел в начале строки. Чтобы этого избежать, в этих случаях, следует писать точку со знаком обратного слеша ( \ ) перед ней:

1986\. Какой прекрасный год.

Блоки кода

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

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

Это обычный параграф:

    Это блок кода.

Markdown сделает:

<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 разметки с использованием Markdown — просто вставьте его, а Markdown преобразует амперсанды и угловые скобки. Например:

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

превратится в:

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

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

Горизонтальные разделители

Чтобы вставить в текст горизонтальный разделитель

---

вставьте в отельную строку 3 или более звездочек, тире, или подчеркиваний:

***
*****
---

все это - приводится к виду:

---

Строковые элементы

Ссылки

Markdown поддерживает два стиля форматирования ссылок: inline (внутритекстовые) и reference (сносные) .

И в том, и в другом стиле текст ссылки ограничивается [ квадратными скобками ].

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

Это [пример](http://example.com/ "Название") inline ссылки.
[А у этой ссыки]( [[http://example.net/][http://example.net/]]) нет названия.

Что обрабатывается как:

<p>Это <a href="http://example.com/" title="Название">
пример</a> inline ссылки.</p>
<p><a href="http://example.net/">А у этой ссылки</a> нет названия.</p>

Если вы ссылаетесь на локальную директорию, вы можете использовать локальный (от текущей страницы/сайта и т.д.) путь:

Вот немного [обо мне](/about/) для тех кому интересно. 

Reference-стилизованные ссылки используют еще одну пару квадратных скобок, в которой пишется идентификатор ссылки:

Это [пример][идентификатор] reference-стилизованной ссылки.

Можно использовать пробел, чтобы отделять 2 пары квадратных скобок:

Это [пример] [идентификатор] reference-стилизованной ссылки.

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

[идентификатор]: http://example.com/ "Здесь можно написать название"

Схема ссылки:

• квадратные скобки [ ] с идентификатором ссылки (может быть отформатировано отступом размером не больше 3 пробелов);

• затем двоеточие : ;

• после один или несколько пробелов (или табуляций);

• далее URL ссылки;

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

Все эти определения идентификатора эквивалентны:

[foo]: http://example.com/ "Здесь можно написать название"
[foo]: http://example.com/ 'Здесь можно написать название'
[foo]: http://example.com/ (Здесь можно написать название)

Также, по желанию, можно заключить URL в угловые скобки:

[идентификатор]: <http://example.com/> "Здесь можно написать название"

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

[идентификатор]: http://example.com/longish/path/to/resource/here
"Здесь можно написать название"

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

Сами идентификаторы могут быть чем угодно, они могут состоять из букв, чисел, пробелов или знаков препинания — но они не чувствительны к регистру букв. Т.е эти 2 варианта:

[текст ссылки][a]
[текст ссылки][A]

эквивалентны.

Можно неявно выражать идентификатор, сокращая его. Тогда, за идентификатор будет принят текст ссылки. Например, чтобы слово “Google” ссылалось на google.com, надо просто написать:

[Google][]

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

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

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

Посетите [Daring Fireball][] для дополнительной информации.

А затем, так определяется ссылка:

[Daring Fireball]: http://daringfireball.net/

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

Вот пример использования нескольких reference-стилизованных ссылок:

[Google] [1] намного удобнее чем [Yahoo] [2] или [MSN] [3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"

Используя сокращение идентификаторов, следовало бы написать так:

[Google][] намного удобнее чем [Yahoo][] или [MSN][].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"

И то, и другое порождает вот этот HTML код:

<p><a href="http://google.com" title="Google">Google</a> намного
Удобнее чем <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
или <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>

Вот как бы это выглядело в момент форматирования, написанное в inline-стиле:

[Google](http://google.com/ "Google") намного удобнее чем 
[Yahoo](http://search.yahoo.com/ "Yahoo Search") или
[MSN](http://search.msn.com/ "MSN Search").

Reference-стилизованные ссылки хороши не тем, что их удобнее писать. Просто с их использованием документ легче читать.

Выделение

Markdown считает звездочки (*) и подчеркивания (_) символами определяющими выделение текста. Текст, окруженный одной или несколькими * или _ , будет заключен в HTML тэг <em> ; двойные * или _ будут заключены в HTML тэг <strong> . Т.е эти фразы:

*одинарные звездочки*
_одинарные подчеркивания_
**двойные звездочки**
__двойные подчеркивания__

будут обработаны в:

<em>одинарные звездочки</em>
<em>одинарные подчеркивания</em>
<strong>двойные звездочки</strong>
<strong>двойные подчеркивания</strong>

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

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

обороно*способ*ность

Но если с обеих сторон * или _ стоят пробелы, то они будут обработаны как, соответственно, звездочка или подчеркивание.

Если требуется написать звездочку или подчеркивание слитно с текстом следует использовать аналоги этих символов в написании с символом обратного слеша:

\*этот текст окружен звездочками\*

Код

Для того чтобы вставить кусок исходного кода прямо в строку его следует окружить символами апострофа ( ` ). Например:

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

превратится в:

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

Если нужно использовать символ апострофа внутри этого "строкового" кода, следует использовать несколько апострофов для обозначения его границ:

``Тут написан обычный символ апострофа (`).``

что обрабатывается в:

<p><code>Тут написан обычный символ апострофа(`).</code></p>

Границы "строчного" кода могут содержать пробелы – один после открывающей части, один перед закрывающей. Это позволяет поставить апостроф в начале или конце "строчного" кода:

Один апостроф внутри строчного кода: `` ` ``
Ограниченная апострофами строка внутри строчного кода: `` `foo` ``

это превращается в:

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

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

Не используйте тэгов `<blink>`.

в:

<p>Не используйте тэгов <code><blink></code>.</p>

Можно написать это:

`—` это шестнадцатеричный эквивалент `—`.

для

<p><code>&amp;#8212;</code> шестнадцатеричный эквивалент <code>&amp;mdash;</code>.</p>

Картинки

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

Inline-форматирование выглядит так:

![Alt текст](/путь/к/картинке.jpg)
![Alt текст](/путь/к/картинке.jpg "Название картинки (по желанию)")

Что есть:

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

• после пара квадратных скобок, содержащая значение атрибута alt HTML тэга img;

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

Reference-форматирование:

![Alt текст][идентификатор]

Далее следует только определить идентификатор:

[идентификатор]: ссылка/на/картинку "Значение атрибута title (по желанию)"

Как видно из сказанного выше Markdown не имеет функциональности, позволяющей определить размер картинки. Для этого всегда можно использовать обычный HTML тэг <img alt="" src="" />.

Разное

Автоматические ссылки

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

<http://example.com/>

превратится в:

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

Автоматические ссылки также можно использовать для написания электронных адресов. Например:

<address@example.com>

будет преобразовано в что-то вроде:

<a href="mailto:addre
ss@example.co
m">address@exa
mple.com</a>

Что в браузере показывается как ссылка на “address@example.com”.

(Такое представление позволяет обмануть большинство спам-ботов, которые собирают адреса, оставленные пользователями на просторах всемирной паутины. Но всех это точно не обманет.)

Замена символов их написанием с обратным слешем

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

\*просто звездочки\*

Markdown предоставляет возможность замены данных символом бэкслеш эквивалентом:

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