Перейти к содержанию

MkDocs — хостинг внутренней документации

Назначение сервиса

mcdocs публикует Markdown-документацию репозитория (папка docs/) через MkDocs Material. Позволяет разработчикам и администраторам просматривать актуальные инструкции в браузере.

Структура каталогов

config/services/mcdocs/
├─ docker-compose.yaml   # запуск контейнера
└─ .env_example          # переменные окружения

Содержимое документации находится вне контейнера — бинд-контейнер ./../../../docs подключается как /docs.

.env параметры

Переменная Описание
VIRTUAL_HOST Домен для доступа (Traefik)
VIRTUAL_PORT Порт контейнера (8000)
COMPOSE_PROJECT_NAME Префикс контейнера (опц.)

Запуск

cd config/services/mcdocs
cp .env_example .env
# укажите домен

docker compose up -d

Тестовый доступ без Traefik:

docker compose exec mkdocs mkdocs serve -a 0.0.0.0:8000

Авто-обновление контента

MkDocs перезапускается при изменении файлов в docs/. В production используйте pipeline, который делает docker compose restart mkdocs.

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

  1. Создайте Markdown-файл в docs/docs/.
  2. Обновите навигацию в docs/mkdocs.yml.
  3. Изменения появятся на сайте через ~10 секунд.

Плагины

Образ squidfunk/mkdocs-material уже содержит большинство нужных плагинов. Чтобы добавить свой:

services:
  mkdocs:
    environment:
      - MKDOCS_PLUGINS=search,minify-markdown

Backup

Сервис stateless: достаточно хранить каталог docs/ и файл mkdocs.yml.