Поддержка Markdown

Markdown — основной синтаксис исходного текста, поддерживаемый Собиракой. Все файлы с расширением .md, а также все файлы с неопознанными расширениями (то есть не .rst) интерпретируются как файлы в формате Markdown.

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

По сравнению с конфигурацией Pandoc по умолчанию, в Собираке выключены расширения citations, smart, raw_html, raw_tex и implicit_figures, а также добавлено расширение mark. Также в файлах Markdown, как и в любых текстовых файлах для Собираки, можно использовать директивы и синтаксис Jinja.

Ниже перечислены некоторые наиболее важные особенности Pandoc Markdown и порядок их обработки.

Заголовки #

Заголовок первого уровня указывается перед текстом страницы и начинается с #. У страницы может быть только один заголовок первого уровня.

По умолчанию текст заголовка будет использован при формировании ссылки на страницу из оглавления. На это поведение можно повлиять с помощью свойств toc_title и title.

Если в конце заголовка стоит конструкция {-}, Собирака исключает его из автонумерации.

Подзаголовки #

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

Если в конце подзаголовка стоит конструкция {-}, Собирака исключает его из автонумерации.

Каждому подзаголовку назначается идентификатор (см. header_attributes). Этот идентификатор следует указывать в ссылках на подзаголовок, а при сборке HTML он же может быть виден читателю в строке браузера при переходе к подзаголовку из оглавления.

Если идентификатор не указан явно, то он формируется автоматически на основе текста подзаголовка. За автоматическое формирование идентификатора отвечает Pandoc Markdown (см. auto_identifiers), но это поведение может измениться в будущих версиях Собираки. Для подзаголовков, ссылки на которые важно сохранять неизменными, рекомендуется указывать идентификаторы эксплицитно.

Пример. В документе, показанном ниже, первый подзаголовок получит автоматический идентификатор шаг-первый-взять, а второй — вручную указанный идентификатор step2.

# Как сделать
## Шаг первый: взять
## Шаг второй: сделать {#step2}

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

Обработка всех ссылок, в том числе написанных как reference links, происходит в соответствии с правилами, описанными в разделе Ссылки.

Инфоблоки #

Инфоблоки не являются отдельным типом с точки зрения Pandoc Markdown, однако конкретная тема оформления может реализовывать специальное оформление для блоков с определёнными классами: например, “info”, “warning”, “example” и т.п. Назначать блокам классы можно с помощью расширения fenced_divs.

Набор поддерживаемых классов зависит от реализованных CSS-классов или реализованных функций process_div_*() в обработчике страниц используемой темы оформления.

Пример. Тема sobiraka2025 поддерживает классы “example”, “note”, “warning” и “danger”. Например, предупреждения в документации можно писать так:

::: warning
Мойте руки после еды, если еда была грязная.
:::

Блоки кода #

Чтобы вставить в документацию блок кода, добавьте три обратных апострофа ``` до и после кода. Опционально к апострофам перед кодом можно добавить обозначение синтаксиса, например, ```json — для таких блоков может работать подсветка синтаксиса. Есть и более сложные способы оформления вставок кода.

```json
{"result": 42}
```

При сборке HTML-документации Собирака позволяет включить подсветку синтаксиса через библиотеки highlight.js, Prism или Pygments — в зависимости от настройки web.highlight. У каждой библиотеки свой набор поддерживаемых языков и свой набор стандартных стилей.

При сборке PDF-документации можно использовать только Pygments — её следует включить настройкой pdf.highlight.

Обратите внимание, что поведение библиотеки Pygments (при использовании для HTML или PDF) может меняться в зависимости от аргументов, переданных при инициализации лексера. Полный список аргументов для каждого лексера приведён в официальной документации. Так, лексер PhpLexer, отвечающий в Pygments за подсветку языка PHP, не подсвечивает PHP-код без открывающего тега <?php, если ему не передан аргумент startinline=true. Чтобы передать этот или любой другой аргумент, укажите его в фигурных скобках (см. синтаксис fenced_code_attributes в Pandoc). Например:

```php {startinline=true}
echo 'Hello, world!'
```

Низкоуровневый код #

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

Фрагменты с конструкцией {=html} включаются без изменений в HTML-файлы, но опускаются при сборке PDF.

Фрагменты с конструкцией {=tex} включаются без изменений в LaTeX-код для PDF-файлов, но опускаются при сборке HTML.

Пример. Конструкция, приведённая ниже, превращается в LaTeX-команду \clearpage (разрыв страницы) при сборке PDF. Конструкция полностью игнорируется при сборке HTML.

`\clearpage`{=tex}