Руководство по настройке

Это руководство описывает основные параметры конфигурации проекта Docs-as-Code Portfolio.

Файл mkdocs.yml

Основная конфигурация находится в файле mkdocs.yml. Рассмотрим ключевые секции.

Название и описание сайта

site_name: Docs-as-Code Portfolio
site_description: Пример портфолио технического писателя с подходом Docs-as-Code
site_author: Милько Дмитрий Иванович

Тема оформления

Используется тема Material с поддержкой тёмной и светлой тем:

theme:
  name: material
  language: ru
  palette:
    - scheme: default
      primary: indigo

Расширения Markdown

Поддержка диаграмм Mermaid, вкладок и других элементов:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
  - pymdownx.tabbed

Навигация

Структура меню сайта задаётся в секции nav:

nav:
  - Главная: index.md
  - Быстрый старт: quickstart.md

Добавление новой страницы

1. Создайте файл в папке docs/.
2. Добавьте запись в секцию nav файла mkdocs.yml.
3. Сохраните изменения — MkDocs автоматически подхватит их.

Полезные настройки

Смена порта сервера

mkdocs serve -a 0.0.0.0:8080

Отключение минификации

Закомментируйте или удалите плагин minify из секции plugins:

plugins:
  - search
  # - minify:
  #     minify_html: true

Что дальше?

• Руководство по интеграции — подключение внешних сервисов.
• Устранение неполадок — решение частых проблем.
• API Reference — документация REST API.
• Чек-лист ревью — как проверяется документация.
• Стайлгайд — правила оформления.