Markdown, HTML и Bootstrap3

Формат Markdown прост в освоении, но беден нюансами оформления текста. Собственно говоря, это не его задача — для этого существуют более продвинутые форматы. Но если все же хочется совместить простоту Markdown и немного тех самых нюансов? Добиться этого можно, помещая в Markdown-документ фрагменты оформления в целевом формате. Например, если вы хотите получить из Markdown LaTeX-овский файл, то и включайте в Markdown куски разметки на LaTeX. Мы уже рассматривали этот подход здесь и здесь. Сейчас поговорим о том, как дооформить в Markdown будущие веб-страницы: ситуация обычная для статических генераторов сайтов, вроде используемого мною Pelican.

Обтекаемый рисунок

Обтекаемый текстом рисунок расположен слева от абзаца:

![Caption](./images/myimage.png "alt text"){ align=left }
Текст абзаца.

Важно:

• Рисунок непосредственно примыкает к тексту абзаца (без пустых строк, которые будут разрывать абзацы).
• Атрибут align, а не float.
• Несмотря на наличие фигурных скобок, атрибуты задаются как в HTML (через =), а не как в CSS.

Установка размеров изображений

Используем атрибуты height и width. Принцип тот же, что и выше:

![Caption](./images/myimage.png){ width=250px }

или

![Caption](./images/myimage.png){ height=256px }

Результат преобразования Markup -> HTML будет выглядеть как

<img src="./images/myimage.png" alt="Caption" style="width: 250px;"/>

и

<img src="./images/myimage.png" alt="Caption" style="height: 256px;"/> 

Атрибут rel='nofollow'

Иногда нужно указать роботу поискового сервиса, чтобы он не покидал ваш сайт по ссылке. Делается это с помощью атрибута rel='nofollow' тега <a>:

[Bootstrap3](https://github.com/getpelican/pelican-themes/tree/master/pelican-bootstrap3){rel="nofollow"}

Выравнивание рисунков в Bootstrap3

Для выравнивания рисунка по центру в Bootstrap3 существует класс .center-block:

<img src="./images/myimage.png" alt="alt text" class="img-responsive center-block" />

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

![]({filename}/path/to/image.jpg){class="img-responsive center-block"}

Для выравнивания по правому краю существует класс class="img-responsive pull-right".

Все это можно было бы легко сделать и без Bootstrap3. Например, так

<div style="text-align:center">Текст, выровненный по центру.</div>

и

<div style="text-align:center">
![Alt Text](/path/to/image "Caption")
</div>

Но если Bootstrap3 уже установлен как тема по умолчанию, зачем плодить новые стили?

Подпись под рисунком

можно реализовать с помощью класса .text-center из Bootstrap3:

<div class="text-center">Текст подписи</div>

Разрыв строки

В месте разрыва ставим <br/>.

Размер шрифта

<div style="font-size: 80%;">Шрифт размера 80% от обычного.</div>

Автоматическое содержание в Pelican

Реализуется с помощью расширения Markdown (toc). Это расширение нужно подключить, указав в конфигурационном файле pelicanconf.py:

MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
        'markdown.extensions.toc': {},
    },
    'output_format': 'html5',
}

В текст статьи (файл *.md) содержание включается при помощи [TOC].

Сноски

Footnotes[^1] have a label[^@#$%] and the footnote's content.

[^1]: This is a footnote content.
[^@#$%]: A footnote on the label: "@#$%".

Внутренние ссылки

Цель гиперссылки (якорь) помечается как <a name="foo"/>, т. е. используется обычный HTML. Сама ссылка, реализуется средствами Markdown:

[Переход к ссылке foo](#foo)