Pelican и использование Markdown
Содержание
Зачем Markdown
Строго говоря, написанное под этим заголовком существенной частью относится и к reStructuredText, но беглый взгляд на два текста, написанных в этих форматах, лично меня склонил именно к .md, хотя и пришлось ставить дополнительный модуль для Python.
Markdown — упрощенный (или облегченный) язык разметки. В отличие от, скажем, HTML, который тоже язык разметки, но не упрощенный и не облегченный, Markdown сам по себе практически не используется, а служит промежуточным «буфером» для последующего преобразования в другой язык, который будет отображаться, в нашем случае — в HTML, но можно и в Rich Text, XML или еще куда-нибудь.
Markdown хорош тем, что с его использованием писать статью существенно быстрее и проще, нежели непосредственно на HTML. В ряде случаев необходимые HTML-теги будут вставлены в сгенерированный текст в соответствии с контекстом (и ничего специально писать не надо), например, абзацы или списки. В других случаях некие пометки добавить все же надо — например, два пробела в конце строки вместо тега <br> или ## перед заголовком вместо обрамления ее тегами <h2> .. </h2>, однако эти символы добавляются проще и быстрее тегов. Их использование нисколько не ухудшает человекочитаемость, ведь строчка из звездочек больше похожа на линию отчеркивания, чем знакосочетание <hr> Кроме того, можно довольно быстро переделать форматированием в Markdown готовый текст, написанный без разметки.
Вольный перевод кусочка из официальной документации:
Markdown — не замена HTML. Его синтаксис охватывает только очень малое подмножество HTML-тегов. Идея состоит не в том, чтобы упростить ввод тегов. По моему мнению, HTML-теги и так уже просты для вставки. Идея Markdown в том, чтобы упростить чтение, запись и редактирование прозы. HTML — это формат для публикации, а Markdown — формат для написания.
На заметку тем, кто знает HTML, как родной, и предпочитает писать сразу на нем (благо, Pelican это позволяет): еще одно преимущество Markdown, весьма заметное при желании поделиться в тексте примером кода с красиво (ну, или хоть как-нибудь) подсвеченным синтаксисом — pygments (который это умеет) работает в связке именно с «буфером», Markdown или reStructuredText. На HTML будет недостаточно окружить код тегами <code> .. </code>, придется каждый элемент кода, который надо выделить особым образом, окружать соответствующими тегами, типа <span class="n">href</span>, а потом писать в CSS-файле способ отображения класса «n». А pygments может сделать все это самостоятельно.
Простые примеры
Как я уже упоминал в другой статье, описания и примеров этого дела в интернете немало. Но добавлю все же и здесь, в формате «код — вид». Основные синтаксические штучки, доступные в пеликане «из коробки», что надо написать, и как это будет выглядеть:
Заголовки
Статья начинается с заголовка, так что и здесь начнем с них же — заголовки (количество символов # соответствует числу n в теге <hn>). Если код заголовков такой:
# Заголовок 1
## Заголовок 2 с id {#id_header2}
###### Заголовок 6
####### Заголовок 7
заголовок
=========
заголовок
---------
то результат будет такой:
Заголовок 1
Заголовок 2 с id
Заголовок 6
# Заголовок 7
заголовок
заголовок
Забавно, что если поставить больше 6 знаков #, то 6 из них воспримутся в качестве уровня заголовка, а остальные войдут в текст заголовка. Остальные будут отображаться в соответствии с таблицами стилей, как задано для <h1> – <h6>. А еще заголовок можно отчеркнуть минусами или знаком равенства, получится второй и первый уровни соответственно, при этом, надо такой заголовок отделить с обеих сторон пустыми строками, как абзац.
Горизонтальные линии
Линии отчеркивания можно нарисовать звездочками, минусами или символом подчеркивания, слитно или через пробелы. Только надо следить, чтобы у них тоже сверху и снизу были пустые строки, а то при обработке их могут принять за часть заголовка или маркированного списка. А вот линия из знаков равенства ничего особенного не делает и рисуется, как есть. Вот код линий и результат:
******
* * * *
-------
- - - -
_______
_ _ _ _
=====================
=====================
Таблицы
Таблицы можно разметить псевдографикой. Границы по умолчанию не прорисовываются, заголовки по умолчанию центрируются (поведение корректируется при помощи CSS), а выравнивание строк в столбце можно отрегулировать двоеточием в разделительной линии ниже заголовка. Вот код таблицы:
| 1 | 2 (правый) | 3 (центр) |
|---|-----------:|:---------:|
| ячейка 1.1 | ячейка 2.1 | ячейка 3.1
| 1.2 | 2.2 | 3.2 так
| 1.3 | 2.3 с буквами | 3.3 и сяк
И вот что из этого получается:
| 1 | 2 (правый) | 3 (центр) |
|---|---|---|
| ячейка 1.1 | ячейка 2.1 | ячейка 3.1 |
| 1.2 | 2.2 | 3.2 так |
| 1.3 | 2.3 с буквами | 3.3 и сяк |
Абзацы и внутристрочные элементы
Вот код всякого рода внутристрочных элементов:
<!-- Можно использовать комментарии
в стиле HTML, чтобы не показывать
часть текста в обработанной странице -->
Пример Footnote[^1] в тексте. Будет
вынесена вниз страницы.
<!-- Такие штуки надо размещать сразу же: -->
[^1]: Footnote по-русски — сноска
Словарь
: книга, содержащая перечень слов
с пояснениями и толкованиями
пример аббревиатуры: ИМХО
<!-- Такие штуки тоже надо размещать сразу же: -->
*[ИМХО]: Имею Мнение — Хрен Оспоришь
Абзац создается разделением
пустыми строками,
даже если строки абзаца
имеют простые переносы.
Однако, по два пробела
на концах строк делают
перенос строки без абзаца:
**выделение** тегом __strong__
*выделение* тегом _emphasize_
***можно*** оба __*сразу*__
внутристрочный `<h1>блок кода</h1>`
А вот результат:
Пример Footnote1 в тексте. Будет вынесена вниз страницы.
- Словарь
- книга, содержащая перечень слов с пояснениями и толкованиями
пример аббревиатуры: ИМХО
Абзац создается разделением пустыми строками, даже если строки абзаца имеют простые переносы.
Однако, по два пробела
на концах строк делают
перенос строки без абзаца:
выделение тегом strong
выделение тегом emphasize
можно оба сразу
внутристрочный <h1>блок кода</h1>
Некоторые символы могут иметь особое значение. Вот пример их использования:
Использование HTML-тегов:
<span style="text-shadow: black
1px 1px 2px, red 0 0 1em;
text-transform: uppercase;">пример</span>
использование спецсимволов
(пример): © »—«
использование служебных символов:
< > * [ ] { } ( ) \ _ # + - . !
использование служебных символов
в сложных случаях:
<a\> \[a\]\(a\) \`a\` \_a\_ #a
\##a
Получится так:
Использование HTML-тегов: пример
использование спецсимволов
(пример): © »—«
использование служебных символов:
< > * [ ] { } ( ) \ _ # + - . !
использование служебных символов
в сложных случаях:
<a> [a](a) `a` _a_ #a
##a
В общих случаях генератор веб-страниц достаточно умен, чтобы понять, используется угловая скобка для обозначения HTML-тега или сама по себе, в других целях. То же касается и прочих символов, которые могут быть служебными как для HTML, так и для самого Markdown. Также он догадывается, что если # не в начале строки — то это не заголовок, если скобки [] и () не вплотную друг к другу — то это не ссылка. В тех же случаях, когда использование таких символов очень уж похоже на служебное, следует подсказать генератору оставить символ в покое при помощи традиционного обратного слэша. Причем, для угловых скобок достаточно закрыть закрывающую (простите за тавтологию, но так уж есть).
Блочная разметка: цитаты и блоки кода
Под блоками кода подразумеваются блоки предварительно отформатированного текста, которые будут отображаться так, как их напечатали, а не по правилам HTML или Markdown. При этом, в них можно включить подсветку синтаксиса, если это действительно программный код. Подсветку необходимо предварительно настроить, добавив файл CSS для кода, а также подключить способом, предусмотренным в используемой теме: либо в файле конфигурации, либо напрямую в шаблоне. Цитаты упаковываются в теги <blockquote>, и их отображение можно настроить в стилевом файле. Вод код примера:
> Цитата умного человека —
почти афоризм.
или так (то же самое):
> Цитата умного человека —
> почти афоризм.
Отступ в 4 пробела или 1 таб:
будет окружено тегом <pre>,
а если включена подсветка -
то и подсвечено. Можно печатать
всё: [a](http://a) <html> `ы`
Сделано для блоков кода.
```
:::c
void sample_func(int j) {
printf(j);
}
for (int i = 0; i < 9; i++) {
sample_func(i);
}
/*
* по сути, то же самое, плюс
* указание языка для подсветки.
* вместо ``` можно
* использовать ~~~
*/
```
Вот результат обработки:
Цитата умного человека — почти афоризм.
или так (то же самое):
Цитата умного человека — почти афоризм.
Отступ в 4 пробела или 1 таб:
будет окружено тегом <pre>,
а если включена подсветка -
то и подсвечено. Можно печатать
всё: [a](http://a) <html> `ы`
Сделано для блоков кода.
void sample_func(int j) {
printf(j);
}
for (int i = 0; i < 9; i++) {
sample_func(i);
}
/*
* по сути, то же самое, плюс
* указание языка для подсветки.
* вместо ``` можно
* использовать ~~~
*/
Цитаты могут быть вложенными, если угловые скобочки удвоить. Кроме того, в цитаты можно вкладывать другие форматированные штучки, типа внутристрочного кода или списков.
Списки
Код разных вариантов списков:
Маркированный:
* пункт
* еще пункт
Нумерованный:
1. первый
2. второй
Смешанный:
1. пунктик с подпунктиками
* 4 пробела дают
+ вложенность, а маркеры
- могут быть разными
3. Цифры тоже неважны,
98. лишь бы цифры.
Можно сделать абзац
внутри списка
* и даже внутри подпункта
тоже можно сделать абзац.
* Еще одна вложенность.
7. Надо только не забывать
отступы и пустые строки.
А вот и сами списки:
Маркированный:
- пункт
- еще пункт
Нумерованный:
- первый
- второй
Смешанный:
- пунктик с подпунктиками
- 4 пробела дают
- вложенность, а маркеры
- могут быть разными
- Цифры тоже неважны,
-
лишь бы цифры.
Можно сделать абзац внутри списка
-
и даже внутри подпункта
тоже можно сделать абзац.
-
Еще одна вложенность.
-
-
Надо только не забывать отступы и пустые строки.
Ссылки, картинки и их комбинация
Простая автоматическая ссылка:
<http://romeogolf.github.io>
Чуть посложнее:
[Мой сайт](http://romeogolf.github.io "Ссылка")
Ссылочная (сносочная? референсная?)
ссылка: [Снова мой сайт][my_site]
или так: [Site][]
А где-нибудь ниже по тексту надо
определить ссылку по указанному
идентификатору.
Ссылка на [заголовок](#id_header2),
который мы пометили идентификатором выше
Ссылка на собственную страницу,
еще в исходном тексте:
абсолютная (от корня content)
[Рыба]({filename}/pages/test_page.md)
или относительно этой страницы
[Рыба]({filename}../../pages/test_page.md)
Статьи с тегом [pelican]({tag}pelican)
или в категории [Блог]({category}Блог)
Картинка напрямую:
или через исходное размещение:
<!-- устаревший вариант:
-->
Картинка через сноску:
![флаги romeo и golf][flags]
Картинка и ссылка вместе:
[![флаги][flags]][my_site]
или так:
[](http://romeogolf.github.io/)
[my_site]: http://romeogolf.github.io/
[Site]: http://romeogolf.github.io/ "Ссылка"
[flags]: ./images/rg.png (romeo golf)
Простая автоматическая ссылка:
http://romeogolf.github.io
Чуть посложнее: Мой сайт
Ссылочная (сносочная? референсная?)
ссылка: Снова мой сайт
или так: Site
А где-нибудь ниже по тексту надо
определить ссылку по указанному
идентификатору.
Ссылка на заголовок,
который мы пометили идентификатором выше
Ссылка на собственную страницу,
еще в исходном тексте:
абсолютная (от корня content)
Рыба
или относительно этой страницы
Рыба
Статьи с тегом pelican
или в категории Блог
Картинка напрямую:
или через исходное размещение:
Картинка через сноску:
Картинка и ссылка вместе:
или так:
Как видно из примера, картинка отличается от ссылки восклицательным знаком перед первой скобкой. В первых квадратных скобках идет текст ссылки или альтернативный текст для картинки (который отображается, если картинку по какой-то причине не видно), в круглых скобках — путь к объекту, а также необязательный текст в кавычках, который будет атрибутом title (во всплывающей подсказке при наведении мыши на ссылку или картинку).
Удобно пользоваться сносочноым типом ссылки, когда вместо адреса в круглых скобках пишется идентификатор в квадратных, а ниже дается расшифровка — тоже путь к объекту и необязательный title в кавычках (одинарных или двойных) или скобках. Ссылка через сноску хороша тем, что можно использовать одну и ту же ссылку или картинку в нескольких местах по тексту. Кроме того, удобно держать все ссылки рядом, на случай, если придется их перестраивать.
При сносочном типе ссылки можно вторую пару квадратных скобок оставить пустой или вообще не ставить, тогда текст ссылки сам будет сноской, которую надо использовать ниже при указании адреса.
На собственные файлы (страницы или картинки) можно ссылаться как напрямую, зная, где они окажутся в структуре сайта после генерации, так и на исходник. Второй вариант предпочтительнее, так как, во-первых, не нужно задумываться о структуре сайта при его наполнении контентом, а во-вторых, структура может поменяться, скажем, в результате автоматизированной архивации старых статей с перемещением их в соответствующие папки.
Аналогично файлам в исходниках, можно ссылаться на категории или теги, с соответствующим префиксом в фигурных скобках.
Некоторые особенности и тонкости
- Необходимо быть достаточно внимательным с пустыми строками, отступами и пробелами в концах строк, так как они здесь играют роль тегов, а наличие и количество пробелов видно плохо.
- Если четыре пробела (или один таб) идут перед первой строкой абзаца — абзац считается блоком кода.
- Если четыре пробела идут перед первой строкой абзаца, следующего сразу после пункта списка — абзац считается дополнительным абзацем первого уровня текущего пункта списка. Если при этом над пустой строкой был второй уровень вложенности — абзац все равно будет сдвинут до первого уровня, а если надо, чтобы он принадлежал второму уровню, то надо ставить восемь пробелов.
- Если в списке вставить явным образом блок кода (через
~~~), то последующие абзацы с четырьмя пробелами в начале будут считаться тоже блоками кода. - Если явно указанный блок кода будет еще и с отступом, то он будет воспринят некорректно, будет пропущено указание языка для подсветки
:::язык. - Чтобы запихать блок кода в список, надо «утопить» его отступами дважды — восемь пробелов для первого уровня, при этом оформить абзацным методом, без
~~~. - Чтобы использовать HTML-код в Markdown по прямому назначению, он не должен быть «утоплен» на четыре пробела, иначе будет восприниматься, как блок кода, то есть, не для использования, а для отображения.
- Блочные HTML-теги, например,
<div>, должны быть отделены выше и ниже пустой строкой. - В HTML-коде внутри блочных тегов не работает разметка Markdown, ее конструкции будут выводиться без обработки, как есть. Вопрос частично решаемый, но об этом в другой раз.
<div style="float:right">
<!-- устаревший вариант:
-->
</div>
<div style="display:inline-block; margin:10px">
Попытка вставить картинку
в плавающий блок </div>
- Существуют разные реализации Markdown. Описания некоторых особенностей синтаксиса могут не соответствовать действительности для питонового модуля. Например, поддерживаемая на GitHub возможность делать зачеркнутый текст
~~striked~~здесь не работает. Автоматические ссылки без явного указания при помощи угловых скобок тоже не поддерживаются, ссылкообразное знакосочетание в тексте само преобразовано в ссылку не будет. - Существуют расширения Markdown, которые позволяют обойти некоторые ограничения и добавить функциональные возможности. Одни расширения фактически являются общими для разных реализаций Markdown (потому что написаны для разных языков — Perl, Python, Ruby, Java, … Там, вообще-то, приличный список.) Другие присутствуют только в некоторых реализациях. Расширения могут быть встроенными в реализацию, а могут быть установлены отдельно. Их можно включать и отключать. Расширения, которые можно использовать в реализации для Python, могут оказаться удобными и полезными при создании сайта (если хотите — блога) на Pelican. Но это тема для отдельного разговора.
-
Footnote по-русски — сноска ↩