Розробка сайту документації на MkDocs під ключ

Розробка сайту документації на 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-специфікацій — за запитом.

Який процес розробки?

1. Аналітика: вивчаємо ваш проект, визначаємо структуру документації.
2. Проектування: створюємо карту розділів, обираємо плагіни.
3. Реалізація: конфігуруємо MkDocs, пишемо кастомні плагіни при необхідності.
4. Тест: перевіряємо збірку, швидкість завантаження, пошук. Для складних проектів додаємо етап UX-тестування документації з реальними розробниками.
5. Деплой: налаштовуємо автоматичну публікацію.

Приклад: міграція документації API з Sphinx на MkDocs

Один із проектів — міграція документації REST API з Sphinx на MkDocs. Вихідний сайт генерувався 3 хвилини, пошук працював повільно, а підтримка Markdown була обмежена. Ми перенесли 200 сторінок, налаштували Material for MkDocs з плагінами mkdocs-openapi-ref та mkdocs-table-reader. Час генерації скоротився до 25 секунд, пошук став миттєвим, а розробники почали частіше оновлювати документацію — частота комітів зросла в 3 рази. Перехід окупився за 2 місяці за рахунок зниження часу на пошук та усунення помилок.

!!! 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 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 вже сьогодні.