Простая разметка текста для сайтов: Markdown

Давно хотел написать об этом.

Самым традиционным способом разметки стороны пользователя в Web являются BB-коды (BB - от bulletin board). Большинство форумных движков, web-чатов, блогов используют HTML-подобные элементы вида This [b]text[/b] [i]is[/i] [color=red]red[/color] для оформления текста различными шрифтами, внедрения ссылок и изображений. Позволять пользователям внедрять HTML-тэги <a>, <img> опасно, а контролируемые на стороне движка BB-коды дают возможность и пользователям картиночки ембеддить, и разработчикам не париться по поводу возможных XSS-уязвимостей. Реализовать BB-коды нетрудно в том числе и из-за их похожести на HTML.

Суксом BB-кодов является низкое (никакое) соответствие текстового сырца и распарсенного итога, отображаемого на странице. ИМХО, это полный отстой и совершенно не труъ. Хотя BB-разметка и достаточно привычна большинству сетян, реально использовать другие, возможно более мудрые, способы оформлять посты в блоги/форумы/чаты при написании вместо BB-кодов, особенно на блогах.

Markdown

Например, разметка Markdown. Она мнемонична, понятна и смотрится хорошо и в текстовом, и в парсеном виде. Задумывался Markdown специально в качестве user-side разметки для написания текстов с тем условием, чтобы такую разметку было удобно и писать, и читать. Markdown переносит работу по оформлению текста на чуть более высокий уровень абстракции по сравнению с BB-кодами, делая её более понятной интуитивно. Стоит отметить, что на выходе для элементов оформления Markdown даёт не <b></b> уровня представления с кучками <br />, а структурные <em></em>, <p></p> и т. п.

В целом синтаксис Markdown во многом обусловлен традициями оформления электронных писем в формате простого текста.


Пример текста, размеченного при помощи Markdown

Для смыслового выделения текста в Markdown можно использовать
*звёздочки* или символы __подчёркивания__.

Когда нужно написать в тексте именно звёздочку (asterisk), её нужно
экранировать так: 5\*5=24. Так же - для других управляющих символов.

Исходный текст, который должен выводиться моноширинным шрифтом,
внедряется (в span-стиле) при помощи апострофов: `<?php phpinfo(); ?>`.

При выводе такой `text` в апострофах оборачивается тэгами `<pre>` и
`<code>`.

Написать целый блок текста моноширинным шрифтом можно, отступив от края
страницы 4 пробела. Например, так был написан весь этот пример.

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

Можно, однако, вставлять жёсткий разрыв строки,\
в конце строки добавляя обратную косую черту.

Списки пишутся так, как пишутся списки :)

1. foo
3. bar
2. baz

Можно сбивать нумерацию - на выходе получаются `<li>`, за рендеринг
которых ручается браузер.

Ссылки можно писать в полной форме: [текст](http://www.google.com) или
[текст](http://www.google.com "Google").

Или же в reference-стиле, как в книгах: [текст][1], а в конце текста
добавлять такую строчку (она не появится на выводе):

[1]: http://www.wikipedia.org "Ссылка на клёвый сайт"

> Начало цитируемого абзаца обозначается знаком "больше". Можно
> цитировать многострочный текст и при помощи написания знака "больше" в
> начале каждой цитируемой строки, цитата всё равно развернётся в один
> `<blockquote>`.

Изображения внедряются так: ![Alt text](/images/planet.png) или ![Alt
text](/images/planet.png "Логотип").

Изображения, как и ссылки, можно внедрять в reference-стиле.

##### Так выделяется заголовок уровня 5 #####

###### Можно не закрывать его :)

Заголовки уровня 1 и 2 можно выделять подчёркиванием знаками равенства
или чёрточками:

Proud 1-level heading
=====================

Линию (`<hr />`) можно вывести так (можно использовать также
звёздочки):

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

Вышеизложенный пример, обработанный фильтром Markdown

Для смыслового выделения текста в Markdown можно использовать звёздочки или символы подчёркивания.

Когда нужно написать в тексте именно звёздочку (asterisk), её нужно экранировать так: 5*5=24. Так же - для других управляющих символов.

Исходный текст, который должен выводиться моноширинным шрифтом, внедряется (в span-стиле) при помощи апострофов: <?php phpinfo(); ?>.

При выводе такой text в апострофах оборачивается тэгами <pre> и <code>.

Написать целый блок текста моноширинным шрифтом можно, отступив от края страницы 4 пробела. Например, так был написан весь этот пример.

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

Можно, однако, вставлять жёсткий разрыв строки,
в конце строки добавляя обратную косую черту.

Списки пишутся так, как пишутся списки :)

  1. foo
  2. bar
  3. baz

Можно сбивать нумерацию - на выходе получаются <li>, за рендеринг которых ручается браузер.

Ссылки можно писать в полной форме: текст или текст.

Или же в reference-стиле, как в книгах: текст, а в конце текста добавлять такую строчку (она не появится на выводе):

Начало цитируемого абзаца обозначается знаком “больше”. Можно цитировать многострочный текст и при помощи написания знака “больше” в начале каждой цитируемой строки, цитата всё равно развернётся в один <blockquote>.

Изображения внедряются так: Alt text или Alt text.

Изображения, как и ссылки, можно внедрять в reference-стиле.

Так выделяется заголовок уровня 5
Можно не закрывать его :)

Заголовки уровня 1 и 2 можно выделять подчёркиванием знаками равенства или чёрточками:

Proud 1-level heading

Линию (<hr />) можно вывести так (можно использовать также звёздочки):


Полное изложение синтаксиса Markdown можно найти на сайте daringfireball.net.

В принципе, в описании Markdown в составе реализации предлагается и возможность внедрения HTML прямо в Markdown-код. Это может быть спорным решением с точки зрения безопасности; в частном случае может потребоваться нестандартная реализация Markdown, корректно вырезающая HTML-теги (при этом нужно не трогать экранированные апострофами тэги)

Если вкратце, то это основное, что есть в Markdown. Эта разметка проста, компактна (в том плане, что держать в голове ментальную модель разметки Markdown гораздо проще, чем BB-коды, потому что при использовании Markdown быстрее срабатывает ассоциативное мышление, которое достаточно дёшево для мозга), семантична и, на мой взгляд, приятна. При просмотре текста, размеченного Markdown’ом, глаз не цепляется за некрасивые и немнемоничные конструкции BB-кодов.

Человек видит [b]текст[/b]. Мозг:

  1. [b][/b] = «полужирный»
  2. [b]текст[/b] = «„текст” полужирным шрифтом»
  3. «На „текст” нужно обратить внимание».

Человек видит __текст__. Мозг:

  1. «На „текст” нужно обратить внимание».

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

ИМХО, Markdown приколен. Мне для этого блога замечательно подходит. На истину не претендую.

Другие применения

Можно в Markdown оформлять сопроводительные записки к релизам программ (и обойтись только ими, если речь идёт о мелких проектах с малым количеством кода) и эти же записки использовать на веб-странице проекта в описательно разделе, например, как на softwaremaniacs.org.

Использование подобной разметки может помочь решить некоторые проблемы с экспортом информации: в RSS можно отдавать необработанный размеченный Markdown’ом текст — это и не ухудшит сильно читаемость ленты, и будет совместимо со всеми программами для чтения RSS.

Минусом может быть чуть большая сложность реализации, что чревато ошибками кодирования. Однако уже есть куча реализаций Markdown-парсера для PHP, Python (такая используется здесь в качестве фильтра, подключенного к шаблонному движку Django) и других языков, ссылки можно найти в статье про Markdown на Википедии.

Похожие средства

Существует ещё несколько «лёгких» языков разметки текста, можно выделить Textile - у него есть некоторые дополнительные возможности, такие как простая разметка таблиц, более широкая поддержка полезных семантических элементов <cite>, <del>, <ins> (это здорово).

Кстати, про них, повышать уровень разметки - круто. Элементы <cite> и прочие - следующий шаг в Web-Нирвану.

Eсть возможность указания типа выравнивания параграфа. Синтаксис элементов уровня блока (например, bq. для цитат) ИМХО недостаточно выразителен и чем-то смахивает на разметку troff. В целом, Textile покрупнее Markdown’а.

За другими примерами можно обратиться к списку «лёгких» языков разметки на Википедии.

git.md