Materal for MkDocs мой любимый движок для построения документации и на нем построена документация HOSTKEY.
В декабре 23-го года Material for MkDocs обновился до версии 9.5, но из-за регрессов переходить на него не решились (и, судя по изменениям, не стоило еще месяц назад). Но сейчас версия уже достаточно стабильная и поправленная, поэтому можно решиться перейти на ветку 9.5.x. На момент написания данного текста релизной является версия 9.5.13.
Обновляемся
Я рекомендую ставить всегда конкретную версию, а не последнюю, а все обновления проверять на тестовом сервере. Для этого используем команду:
pip install mkdocs-material=="version" для установки, и pip install update mkdocs-material=="version" для обновления. В нашем случае version будет 9.5.13.
Но если вы "сидите" на ветке 9.4 или младше, то обновление через стандартный pip install не произойдет, так как 9.5 будет следующей мажорной версией. Поэтому используем команду
pip install --upgrade --force-reinstall mkdocs-material=="version"
Что нового в версии 9.5
В этой версии были перенесены в свободный доступ несколько функций, доступных до этого только за деньги спонсорам проекта. Часть из них уже включена по дефолту, часть нужно прописывать в конфигурационном файле mkdocs.yml самостоятельно.
Privacy plugin. При сборке документации все внешние ассеты (скрипты и прочее) скачиваются и сохраняются локально. Полезная функция, чтобы ваша статически собранная документация не захворала из-за проблем с внешним ресурсом.
Document contributors и Document Autors. Позволяет вывести внизу документа аватар и имя всех контрибуторов данной страницы или только ее автора. Информация берется из вашего GIT-проекта.
Improved tooltips. Теперь можно добавлять маленькие всплывающие подсказки к заголовкам, ссылкам, якорям и иконкам. Я лично не придумал, где это можно использовать и у меня эта функция работала криво, выводя подсказку в стороне от ссылки.
Сontent tabs anchor links. Теперь автоматически создаются якоря-ссылки для вкладок, позволяя вам создавать переходы на конкретные вкладки в тексте. Эта функция полезная и позволяет при оформлении текста, например, под разные операционные системы или методы, ссылаться непосредственно на нужную.
Следующие новые функции я уже применил в документации, и поэтому о них расскажу подробнее.
Автоматическая темная/светлая тема
Ранее также в Material fo MkDocs можно было добавить на страницу переключатель между светлой или темной темой, то теперь появился автоматический вариант, устанавливающий тему в зависимости от настроек вашей системы. Здесь вы можете положиться на дефолтные настройки, но если захотите сделать «как у меня», то вот такой код надо добавить в stylesheets/extra.css вашей документации (и не забыть прописать использование этого CSS-файла в mkdocs.yml):
/* Настройка цветов для светлой и темной тем */
[data-md-color-scheme=default] {
--md-default-fg-color--light: 000;
--md-primary-fg-color: #ff6e42;
}
[data-md-color-scheme=slate] {
--md-default-fg-color--light: hsla(var(--md-hue), 15%, 100%, 0.8);
--md-primary-fg-color: #121215;
}Тут мы прописываем черный цвет переднего плана для основных элементов (заголовки и прочее) для светлой темы (которая default), а для темной темы (slate) изменяем его через изменение яркости. Эти значения мы позже будем также использовать для изменения конкретных элементов, в нашем случае кнопок, под нужную нам тему.
Generic Grid
Это новинка позволяют располагать по сетке произвольные элементы блоков, включая объявления, блоки кода, вкладки контента и многое другое. Теперь в вашей документации вы можете делать вот такие штуки (точнее их можно было делать и раньше, но используя html-код в Markdown файлах). Вам достаточно «обернуть» все в <div class="grid" markdown> ... </div>.
Сразу предупрежу - не используйте generic grid с раскрывающимися объявлениями, так как это приведет к ошибке рендеринга текста за сеткой.
Card grid
Сетка из карточек позволяет красиво оформить главную или индексные страницы документации. Ранее она была доступна только в спонсорской (insiders) ветке, а сейчас всем желающим.
Что было ранее? Для оформления главное страницы можно было использовать таблицу (что и было сделано мной при разработке документации), но тогда вставали два вопроса: Material for MkDocs по дефолту делает ширину колонок по содержимому и вся эта конструкция (в моем случае три колонки) разъезжалось при просмотре в мобильной версии.
Так как MkDocs позволяет добавлять HTML и CSS прямо в текст статьи, то первое было поправлено таким кодом:
<style type="text/css">
.md-typeset__table {
table { width: 100%; }
th, td { width: 33.33%; }
}
</style>Этот CSS-код заставляет отображать три колонки на странице равной ширины, и вы можете применять его для нужных вам страниц, просто разместив в конце статьи (и поправив значения).
Для того, чтобы наша таблица (а точнее три таблица из двух строк и трех колонок) не коллапсировали в мобильной версии, был добавлен такой CSS-код:
<style type="text/css">
@media screen and (max-width: 800px) {
.md-typeset__table {
table { width: 100%; }
th { display: inline-block; }
th { font-size: 0.8rem; }
td { display: none; }
th { width: 100%; }
td { with: 0%; }
}
}
</style>Этот код позволяет переносить колонки и оставить в них только заголовки, убрав текст описания при переходе к мобильной верстке.
Но с появлением Card Grid все стало чуть проще (и мне кажется симпатичней). Вы заключаете все карточки в блок <div class="grid cards" markdown></div>. Синтаксис отдельной карточки будет выглядеть вот так (карточка с иконкой, заголовком со ссылкой, описанием и ссылкой «Подробнее»):
<div class="grid cards" markdown>
- [:fontawesome-solid-gamepad:{ .lg .middle } **Панель управления INVAPI**](./controlpanel/index.md)
---
Панель управления услугами: новые заказы, управление сервером
[:octicons-arrow-right-24: Подробнее](./controlpanel/index.md)
</div>По умолчанию, если у вас включены меню навигации справа и слева, отображает по две карточки в ряд, выравнивание текста идет по левому краю, а в мобильной версии карточки идут друг за другом.
Но если вы хотите 3 карточки в ряд с текстом по центру или хотите убрать строку «Подробнее» из мобильной версии, то нам на помощь опять приходит CSS. Размещаем на странице с нашими карточками в конце такой код:
<style type="text/css">
/* делаем ширину карточек меньше, чтобы влезало в три карточки в ряд на HD+ разрашениях */
.md-typeset .grid {
grid-gap: 0.4rem;
display: grid;
grid-template-columns: repeat(auto-fill, minmax(min(100%, 12rem), 1fr));
margin: 1em 0;
}
/* отображаем содержимое по центру */
.md-typeset ul li p {
text-align: center;
}
/* В мобильной версии отображаем что влазит + убираем ссылку Подробнее" */
@media screen and (max-width: 800px) {
.md-typeset .grid {
grid-template-columns: repeat(auto-fill, minmax(min(100%, 16rem), 1fr));
}
.md-typeset p:not(:first-child) {
display: none;
}
.md-typeset p:not(:last-child) {
display: block;
}
}
</style>В результате получаем такой результат на десктопе и мобильных устройствах:
Следующие вещи работают также и на предыдущих версиях Material for MkDocs, но, думаю, будут также полезны тем, кто решится создать на нем документацию.
Красивые кнопки и светлая/темная тема
Элемента оформления «Кнопка» в Material for MkDocs изначально нет (точнее, есть, но только для клавиш клавиатуры). Поэтому я использовал модификацию зачеркнутого стиля (del). Но для того, чтобы кнопки корректно отображались как в светлой, так и в темной темах, пришлось чуть-чуть повозиться. А точнее, добавить в extra.css следующий код:
/* применяем вместо кнопки элемент del (~~текст~~) */
del {
text-decoration: none;
background-color: var(--md-primary-fg-color);
color: var(--md-default-fg-color--light);
padding: 4px 4px;
border: solid var(--md-default-fg-color--light) 1px;
white-space: nowrap;
border-radius: 5pt;
}Как видно, мы используем переменные цвета элементов, которые используются в светлой или темной теме. В результате при смене темы меняется и цветовое оформление кнопок:
TOC в мобильной версии
Еще одной модификацией (точнее лайфхаком) стало добавление в текст статьи в ее начало мини-содержания из заголовков второго уровня. Здесь пришлось решать две проблемы: по-дефолту в Material for MkDocs не работает нормально слагификация для создания якорей с символами, отличными от латиницы и такой настройки/элемента нет в движке.
Первая проблема решается добавлением в конфигурационный файл mkdocs.yml следующих строк:
markdown_extensions:
- toc:
permalink: true
slugify: !!python/object/apply:pymdownx.slugs.slugifyПосле этого у вас (в том числе и в редакторе вида VS Code) начинают корректно работать автодополнение и после сборки якоря-ссылки вида #русский текст. Достаточно поставить конструкцию ссылки или изображения. Причем работает это как на текущей странице, так и по всему дереву документации.
Для решения второй проблемы, так как добраться до содержания страницы в мобильной версии осиливают не все пользователи (да и не в мобильной тоже), было решено добавить мини-содержание «В этой статье», как сделано, например, в документации у Microsoft. Для этого применили стандартную цитату, чуть «подтюнинговав» ее CSS-кодом.
В начале статьи теперь достаточно разместить (после заголовка страницы первого уровня) следующий код, где списком перечисляем ссылки на заголовки второго уровня:
> **В этой статье**
> - [Порядок использования панели](#порядок-использования-панели)
> - [Описание контрольной панели сервера](#описание-контрольной-панели-сервера)
---А отображение этого текста форматируем с помощью данного CSS-кода в extra.css, уменьшая размер текста и убирая значки списка.
/* Убираем у цитаты значки списков, чтобы сделать мини TOC *
.md-typeset blockquote {
font-size: 0.65rem;
ul { list-style-type: none;}
}Результат получаем следующий (в десктопной и мобильной версиях):
Если вам будут интересны другие вопросы, касаемые Material for MkDocs напишите в комментариях. Буду рад разобрать настройки и поделиться хитростями и не явными способами его применения.
А как все выглядит "в живую" вы можете глянуть непосредственно в собранной документации.
