Настройка Material for MkDocs
Material for MkDocs — наиболее полная тема для MkDocs с версионированием (Mike), аналитикой, Social Cards, Tags и расширенной навигацией.
Установка и базовая конфигурация
pip install mkdocs-material
# Дополнительные плагины
pip install mkdocs-git-revision-date-localized mkdocs-minify-plugin mike pillow cairosvg
Расширенный mkdocs.yml
theme:
name: material
custom_dir: overrides # для переопределения шаблонов
logo: assets/logo.svg
favicon: assets/favicon.png
font:
text: Inter
code: JetBrains Mono
features:
- announce.dismiss
- content.action.edit
- content.action.view
- navigation.footer
- navigation.indexes
- navigation.path # хлебные крошки
- navigation.prune
- navigation.sections
- navigation.tabs
- navigation.tabs.sticky
- navigation.top
- navigation.tracking
- search.highlight
- search.share
- search.suggest
- toc.follow
extra:
version:
provider: mike # версионирование
social:
- icon: fontawesome/brands/github
link: https://github.com/my-org/my-project
analytics:
provider: google
property: G-XXXXXXXXXX
feedback:
title: Эта страница полезна?
ratings:
- icon: material/thumb-up-outline
name: Да, полезно
data: 1
note: Спасибо!
- icon: material/thumb-down-outline
name: Нет, нужно улучшить
data: 0
note: Напишите нам!
Social Cards
plugins:
- social:
cards_layout_options:
background_color: "#1e293b"
color: "#ffffff"
font_family: Inter
Версионирование через Mike
pip install mike
# Деплой версии
mike deploy --push --update-aliases 2.0 latest
mike set-default --push latest
# Список версий
mike list
Кастомизация через overrides
<!-- overrides/main.html -->
{% extends "base.html" %}
{% block announce %}
<div class="md-banner">
🎉 Версия 2.0 вышла! <a href="/changelog">Что нового</a>
</div>
{% endblock %}
{% block styles %}
{{ super() }}
<link rel="stylesheet" href="{{ 'assets/custom.css' | url }}">
{% endblock %}
Tags плагин
plugins:
- tags:
tags_file: tags.md # страница со всеми тегами
# В Markdown:
---
tags:
- API
- Authentication
- Python
---
Полная настройка Material for MkDocs — 4–8 часов.