Разработка сайта на MkDocs (документация)

Разработка сайта на MkDocs (документация)

MkDocs — Python-генератор документации из Markdown. Популярен в Python-проектах и DevOps-командах. Material for MkDocs — наиболее полнофункциональная тема с поиском, версионированием и многоязычностью.

Установка

pip install mkdocs mkdocs-material
mkdocs new my-docs
cd my-docs
mkdocs serve

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: ru
  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: ru
  - tags
  - git-revision-date-localized:
      type: date
      locale: ru
  - 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

Расширенные компоненты Markdown

# Features

!!! 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

```yaml
# .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 темой и 20–50 страницами — 2–4 дня.