Расширения и плагины
Список атрибутов
Это расширение позволяет добавлять HTML атрибуты и CSS практически ко всем Markdown элементам на уровне строк и блоков с помощью специального синтаксиса:
Это расширение необходимо для работы многих других расширений и плагинов.
Кнопка копирования кода
В каждом блоке кода появится кнопка для копирования содержимого:
Включение или отключение кнопки копирования кода для конкретных блоков
Если вы не хотите включать кнопку для всех блоков, можно включить её только для конкретного блока, используя немного другой синтаксис, основанный на расширении Список атрибутов:
Обратите внимание, что сначала должен быть указан шорткод языка блока с дополнительным префиксом ..
Подобным образом можно отключить кнопку копирования для конкретного блока:
Markdown в HTML
По умолчанию Markdown игнорирует содержимое необработанного HTML-элемента блочного уровня.
При включенном расширении md-in-html содержимое необработанного элемента блочного уровня HTML
может быть распаршено как Markdown при добавлении атрибута markdown в открывающий тег.
При этом атрибут markdown будет удален из выходных данных, а все остальные атрибуты будут сохранены:
SuperFences
Расширение позволяет произвольно встраивать блоки кода и контента друг в друга, включая советы, вкладки, списки и любые другие элементы:
Это расширение необходимо для работы многих других расширений и плагинов.
Highlight
Расширение Highlight добавляет поддержку подсветки синтаксиса в блоках кода (с помощью SuperFences) и во вложенных блоках кода (с помощью InlineHilite):
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.superfences
- pymdownx.inlinehilite
Вкладки
Расширение Tabbed позволяет использовать вкладки контента, простой способ группировки связанного контента и блоков кода:
Использование
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```
=== "C++"
``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
Snippets
Расширение Snippets позволяет встраивать в документ содержимое других файлов, например, других документов или файлов с исходным кодом:
Использование
Чтобы встроить содержимое какого-либо файла, нужно написать --8<-- и название файла в кавычках:
--8<-- "filename.py"
Для указания, с какой по какую строчку вы хотите встроить содержимое, укажите номер строки начала и номер строки конца
после название файла, разделив их с помощью ::
- Чтобы встроить содержимое, начиная с какой-то строки, просто используйте
filename.py:3 - Чтобы встроить всё содержимое до какой-то строки, используйте
filename.py::3. В данном случае встроится с 1 по 3 строку. - Чтобы встроить содержимое, начиная с какой-то строки и заканчивая другой, используйте
filename.py:4:6.
Советы
Советы являются отличным вариантом для добавления побочного контента без существенной перегрузки страницы. Material for MkDocs предоставляет несколько различных типов советов и позволяет встраивать в них произвольный контент.
Следующие расширения позволяют сделать советы сворачиваемыми и добавлять в них "вложенное" содержимое:
Использование
Синтаксис советов прост: блок начинается с !!!, после чего следует одно ключевое слово,
используемое в качестве классификатора типа. Содержимое блока начинается с пропуском строки и с отступом в четыре пробела:
!!! note
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.
Note
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.
Иконки
Каждый поддерживаемый тип советов имеет свою иконку, которую можно изменить на любую другую:
Раскройте, чтобы посмотреть альтернативные наборы иконок
theme:
icon:
admonition:
note: octicons/tag-16
abstract: octicons/checklist-16
info: octicons/info-16
tip: octicons/squirrel-16
success: octicons/check-16
question: octicons/question-16
warning: octicons/alert-16
failure: octicons/x-circle-16
danger: octicons/zap-16
bug: octicons/bug-16
example: octicons/beaker-16
quote: octicons/quote-16
theme:
icon:
admonition:
note: fontawesome/solid/note-sticky
abstract: fontawesome/solid/book
info: fontawesome/solid/circle-info
tip: fontawesome/solid/bullhorn
success: fontawesome/solid/check
question: fontawesome/solid/circle-question
warning: fontawesome/solid/triangle-exclamation
failure: fontawesome/solid/bomb
danger: fontawesome/solid/skull
bug: fontawesome/solid/robot
example: fontawesome/solid/flask
quote: fontawesome/solid/quote-left
Изменение заголовка
По умолчанию заголовок совета - название типа, но это можно изменить, добавив строку в кавычках в соответствии с Markdown (включая ссылки и форматирование) после определения типа:
!!! 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.
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.
Удаление заголовка
Аналогично с изменением заголовка, его можно удалить, для этого нужно вставить пустую строку после определения типа (не работает для раскрываемых блоков):
!!! note ""
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.
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.
Раскрываемые блоки
Если включен pymdownx.details и блок совета начинается с ???, а не с !!!, то совет рендерится как раскрываемый блок:
??? note
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.
Note
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.
Если после ??? добавить +, блок рендерится сразу раскрытым:
???+ note
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.
Note
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.
Поддерживаемые типы
note
Note
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.
abstract
Abstract
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.
info
Info
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.
tip
Tip
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.
success
Success
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.
question
Question
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.
warning
Warning
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.
failure
Failure
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.
danger
Danger
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.
bug
Bug
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.
example
Example
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.
quote
Quote
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.
Клавиши
Расширение Keys позволяет с использованием простого синтаксиса рендерить клавиши и их сочетания:
Использование
Ctrl+Alt+Del
Эмодзи
Расширение Emoji автоматически рендерит текстовые указания на эмодзи:
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
Использование
Lightbox
Если вы хотите добавить возможность открывать картинки на полный экран и зумить их, glightbox плагин - прекрасный выбор.
Установите его с помощью pip:
И добавьте в mkdocs.yml:
Использование
<figure markdown>
<figcaption>Рандомная картинка</figcaption>
</figure>