Розробка сайту документації на MkDocs під ключ
Уявіть: бекенд-розробник витрачає пів години, щоб знайти актуальну специфікацію API в розрізнених Markdown-файлах. Через тиждень він використовує застарілу версію — баг, якого могло б не статися. У компаніях з 10+ розробниками така ситуація повторюється щотижня, призводячи до зриву термінів та додаткових витрат на виправлення багів. MkDocs вирішує цю проблему, перетворюючи Markdown на структурований сайт з пошуком та версіонуванням. Ми розробляємо сайти документації на MkDocs під ключ: від вибору теми до налаштування CI/CD. Маємо підтверджений досвід: 150+ проектів з документації за 5 років роботи. MkDocs у 2–3 рази швидше Sphinx при генерації 500+ сторінок.
Проблеми, які вирішує MkDocs
Розрізнені Markdown-файли в репозиторії — хаос. Розробники витрачають до 30% часу на пошук актуальної інформації. Згідно з опитуваннями, до 60% розробників скаржаться на застарілу документацію. MkDocs формує єдину навігацію, автоматично генерує зміст та підтримує повнотекстовий пошук. У проектах з 50+ документами час пошуку скорочується на 40%. Також вирішується проблема застарівання: інтеграція з Git відстежує дати останніх змін, а плагін mkdocs-git-committers показує автора, що підвищує відповідальність.
Чому MkDocs — найкращий вибір для документації?
MkDocs використовує Markdown — просту та читабельну мову розмітки. Не потрібно вивчати reStructuredText або AsciiDoc. Плагіни Material for MkDocs додають анотації коду, діаграми Mermaid, вкладки з прикладами та багато іншого. Material for MkDocs підтримує понад 50 плагінів, включаючи діаграми Mermaid, анотації коду, вкладки з прикладами, що покриває 90% потреб технічної документації. Час завантаження сторінки менше 0,5 с — відмінний показник для Core Web Vitals. Згідно з офіційною документацією Material for MkDocs, тема підтримує понад 50 плагінів та розширень.
Як налаштовуємо Material for MkDocs?
Встановлюємо пакет mkdocs-material та конфігуруємо mkdocs.yml. Приклад базової конфігурації з темною темою, навігацією та пошуком:
site_name: My Project
site_url: https://docs.myproject.com
repo_url: https://github.com/my-org/my-project
repo_name: my-org/my-project
theme:
name: material
language: uk
palette:
- scheme: default
primary: blue
accent: blue
toggle:
icon: material/brightness-7
name: Темна тема
- scheme: slate
primary: blue
accent: blue
toggle:
icon: material/brightness-4
name: Світла тема
features:
- navigation.tabs
- navigation.tabs.sticky
- navigation.sections
- navigation.expand
- navigation.indexes
- navigation.top
- search.highlight
- search.suggest
- content.code.copy
- content.code.annotate
- content.tabs.link
- toc.integrate
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- attr_list
- md_in_html
- tables
- footnotes
- def_list
plugins:
- search:
lang: uk
- tags
- git-revision-date-localized:
type: date
locale: uk
- minify:
minify_html: true
nav:
- Головна: index.md
- Посібник:
- Встановлення: guide/installation.md
- Конфігурація: guide/configuration.md
- Швидкий старт: guide/quickstart.md
- API:
- Огляд: api/overview.md
- Endpoints: api/endpoints.md
- Changelog: changelog.md
Що входить у розробку сайту на MkDocs?
- Базова структура документації (nav, index, changelog).
- Налаштування Material for MkDocs: тема, палітра, іконки, шрифти.
- Конфігурація плагінів: пошук, теги, дати ревізій, мініфікація.
- CI/CD: деплой на GitHub Pages/Netlify/Vercel через GitHub Actions.
- Інструкція з редагування контенту для команди.
- Кастомні скрипти для генерації документації з OpenAPI-специфікацій — за запитом.
Який процес розробки?
- Аналітика: вивчаємо ваш проект, визначаємо структуру документації.
- Проектування: створюємо карту розділів, обираємо плагіни.
- Реалізація: конфігуруємо MkDocs, пишемо кастомні плагіни при необхідності.
- Тест: перевіряємо збірку, швидкість завантаження, пошук. Для складних проектів додаємо етап UX-тестування документації з реальними розробниками.
- Деплой: налаштовуємо автоматичну публікацію.
Приклад: міграція документації API з Sphinx на MkDocs
Один із проектів — міграція документації REST API з Sphinx на MkDocs. Вихідний сайт генерувався 3 хвилини, пошук працював повільно, а підтримка Markdown була обмежена. Ми перенесли 200 сторінок, налаштували Material for MkDocs з плагінами mkdocs-openapi-ref та mkdocs-table-reader. Час генерації скоротився до 25 секунд, пошук став миттєвим, а розробники почали частіше оновлювати документацію — частота комітів зросла в 3 рази. Перехід окупився за 2 місяці за рахунок зниження часу на пошук та усунення помилок.
Розширені компоненти Markdown
!!! tip "Порада"
Використовуйте environment variables для зберігання секретів.
!!! warning "Увага"
Цей метод застарів у версії 2.0.
=== "Python"
```python
import myproject
client = myproject.Client(api_key="...")
```
=== "JavaScript"
```javascript
const client = new MyProject({ apiKey: '...' });
```
```mermaid
sequenceDiagram
Client->>API: POST /auth/login
API->>Database: Check credentials
Database-->>API: User found
API-->>Client: JWT token
Деплой на GitHub Pages
# .github/workflows/docs.yml
name: Deploy Docs
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: actions/setup-python@v5
with: { python-version: '3.x' }
- run: pip install mkdocs-material mkdocs-git-revision-date-localized
- run: mkdocs gh-deploy --force
Порівняння можливостей
| Функція | MkDocs + Material | Sphinx + Read the Docs | GitBook |
|---|---|---|---|
| Мова розмітки | Markdown | reStructuredText / Markdown | Markdown |
| Пошук | Вбудований, з підсвіткою | Через плагіни | Хмарний |
| Версіонування | Плагін mike | Вбудоване | Платна підписка |
| Швидкість генерації (500 стор.) | < 1 хв | 2–3 хв | Хмарна |
| Ціна | Безкоштовно | Безкоштовно | від $8/міс |
Порівняння платформ деплою
| Платформа | Безкоштовний ліміт | Швидкість деплою | Особливості |
|---|---|---|---|
| GitHub Pages | 1 ГБ, 100 ГБ/міс | 30–60 сек | Вбудований CI/CD, Jekyll |
| Netlify | 100 ГБ/міс, 300 хв збірки | 20–40 сек | Форми, функції serverless |
| Vercel | 100 ГБ/міс, 6000 хв збірки | 15–30 сек | Edge Functions, аналітика |
Типові помилки при самостійному налаштуванні
-
mkdocs gh-deployбез пакетаmkdocs-git-revision-date-localized. - Відсутність
navу конфігу — сайт не збереться. - Використання відносних шляхів у
docs_dir— ламається при деплої. - Забувають вимкнути
use_directory_urlsдля локального перегляду. - Кодування файлів: не-UTF-8 ламає пошук. Перевіряємо, що всі .md файли в UTF-8.
Гарантія якості
Ми надаємо офіційну документацію Material for MkDocs як джерело рекомендацій. На кожному проекті проводимо аудит Core Web Vitals та перевіряємо коректність посилань. Результат — документація, яка не застаріває та завантажується за секунду. Звертайтеся за консультацією — оцінимо обсяг та терміни. Замовте розробку документації на MkDocs вже сьогодні.