Skip to content

Set up Markdown callouts in MkDocs

Описание

В нашей конфигурации MkDocs отсутствует возможность оформления выносок. Сейчас в документации есть 15 выносок типа note.

Актуальные выноски в документации Picodata image

Предложения

Описанные далее модули позволяют использовать выноски в MkDocs.

admonition

Расширение Python-Markdown, нативно интегрированное в тему Material для MkDocs. Определяет типы выносок и их стили. Модули, переопределяющие синтаксис оформления выносок, используют именно эти типы. Список типов:

Необходимые настройки в файле конфигурации 
markdown_extensions:
  - admonition
Синтаксис 
!!! note "Phasellus posuere in sem ut cursus"

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

markdown-callouts

Расширение Python-Markdown. Упрощает синтаксис оформления выносок, используемый в расширении admonition.

Необходимые настройки в файле конфигурации 
markdown_extensions:
  - callouts
Синтаксис 
NOTE: **Phasellus posuere in sem ut cursus**
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.

mkdocs-callouts

Плагин MkDocs. Позволяет оформлять выноски с использованием синтаксиса Obsidian.

Необходимые настройки в файле конфигурации 
markdown_extensions:
  - nl2br
  - admonition
  - pymdownx.details
  - pymdownx.superfences

plugins:
  - search
  - callouts
Синтаксис 
> [!NOTE] Phasellus posuere in sem ut cursus
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
> nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
> massa, nec semper lorem quam in massa.

Решение

Оптимальным видится использование расширения markdown-callouts. Основные причины:

  • синтаксис расширения упрощает чтение и написание выноски в исходном файле .md
  • для работы расширения нужна одна настройка в файле конфигурации

See:

Edited by Artur Sabirov