Документація об'ємом 200+ сторінок потребує просунутого налаштування: пошук перестає знаходити потрібне, версіонування страждає, а шеринг посилань не дає прев'ю. Material for MkDocs вирішує ці проблеми з коробки, але тільки при правильній конфігурації. Ми налаштовуємо тему, Social Cards, версіонування через Mike та пошук з підсвічуванням — під ключ.
Які проблеми вирішує налаштування Material for MkDocs?
Екосистема Material for MkDocs — це не просто тема, а потужна платформа. Вбудований пошук з підсвічуванням, навігація з хлібними крихтами, аналітика Google, зворотний зв'язок, тегування — стандартна тема MkDocs не дає й третини цього функціоналу.
Ми стикалися з проектами, де документація розросталася до 200+ сторінок, а пошук переставав знаходити потрібне. Рішення — налаштувати індексацію, додати синоніми та використовувати плагін search.suggest. Інша часта проблема — відсутність версіонування: при виході нової версії продукту стара документація губилася. Mike вирішує це за один деплой. Material for MkDocs генерує Social Cards в 5 разів швидше, ніж ReadTheDocs, і підтримує 15+ плагінів для розширення функціоналу.
Чому варто налаштувати Material for MkDocs професійно?
Самостійне налаштування часто призводить до помилок: неправильний порядок плагінів ламає збірку, Social Cards не генеруються через відсутність залежностей, а версіонування не працює без mike. Ми вже налаштували десятки проектів і знаємо всі підводні камені. Середній час налаштування — 4–8 годин. Економія часу на відладці конфігурації може сягати 20 годин і більше.
Як ми налаштовуємо Material for MkDocs під ключ?
Використовуємо стек: MkDocs Material (остання стабільна версія), Python 3.11+, Mike для версіонування, плагіни git-revision-date-localized, minify, social. У конфігу включаємо navigation.indexes, navigation.tabs, search.suggest, search.highlight. Приклад повного 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: Напишіть нам!
plugins:
- social:
cards_layout_options:
background_color: "#1e293b"
color: "#ffffff"
font_family: Inter
- tags:
tags_file: tags.md
- search:
lang: uk
- git-revision-date-localized
- minify:
minify_html: true
Для генерації Social Cards необхідні бібліотеки pillow та cairosvg. Карти генеруються автоматично для кожної сторінки.
Налаштування версіонування через Mike
Встановіть mike та виконайте:
pip install mike
mike deploy --push --update-aliases 2.0 latest
mike set-default --push latest
Тепер у документації з'явиться перемикач версій. Це дозволяє користувачам перемикатися між стабільною та останньою версією.
Генерація Social Cards
Підключіть плагін social у mkdocs.yml, як показано вище. Переконайтеся, що встановлені pillow та cairosvg. Карти генеруються автоматично при збірці.
Кастомізація через 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 %}
Порівняння з іншими темами
| Функція | Material for MkDocs | Стандартна тема |
|---|---|---|
| Пошук з підсвічуванням | Так | Ні |
| Social Cards | Так | Ні |
| Версіонування | Mike | Відсутнє |
| Темний режим | Так | Ні |
| Аналітика | Google, користувацька | Ні |
Material for MkDocs працює в 5 разів швидше при генерації Social Cards, ніж аналоги, і підтримує 15+ плагінів. Для швидкого старту використовуйте готовий конфіг — зв'яжіться з нами, і ми адаптуємо його під ваш проект.
Вибір плагінів: minify vs social
| Плагін | Призначення | Вплив на швидкість |
|---|---|---|
mkdocs-minify-plugin |
Стиснення HTML/CSS | Прискорює завантаження на 20-30% |
social |
Генерація Social Cards | Збільшує час білду, але дає прев'ю |
Порядок підключення важливий: minify має йти після social, щоб не ламати генерацію карт.
Процес роботи
- Аналізуємо вашу поточну структуру документації та потреби.
- Проектуємо конфігурацію та кастомні шаблони.
- Налаштовуємо тему, Social Cards, версіонування, пошук та додаткові плагіни.
- Тестуємо на staging-оточенні.
- Деплоїмо на продакшн та передаємо доступи.
Строки: від 4 до 8 годин залежно від складності. Вартість розраховується індивідуально.
Чек-лист типових помилок при налаштуванні
- Пропущено встановлення залежностей для Social Cards (pillow, cairosvg).
- Неправильно вказано
custom_dir— overrides не застосовуються. - Версіонування не працює через відсутність
mikeв extra.version.provider. - Пошук не індексує українські тексти без вказання
lang: uk. - Конфлікт плагінів: minify ламає Social Cards — порядок плагінів важливий.
Що входить у роботу
- Повна конфігурація
mkdocs.ymlпід ваш проект. - Налаштування Social Cards з вашим брендингом.
- Налаштування версіонування через Mike.
- Міграція існуючої документації (при необхідності).
- Навчання команди роботі з MkDocs та Mike.
- Гарантія 30 днів на коригування.
Наш досвід — 5+ років роботи з MkDocs, понад 50 проектів документації. У нас є сертифікати та відгуки. Отримайте консультацію з налаштування — ми допоможемо підібрати конфігурацію під ваш проект. Замовте налаштування зараз і отримайте гарантію 30 днів.