Как добавить статью в документацию¶

Когда использовать¶

Каждый раз при добавлении новой страницы в docs.technopriest.net.

Шаги¶

1. Создать файл¶

В папке нужного раздела внутри docs/:

docs/infrastructure/   # инфраструктура: серверы, сети, хостинг
docs/services/         # сервисы: боты, приложения
docs/learning-notes/   # заметки по изученным темам
docs/runbooks/         # операционные инструкции

Имя файла — латиницей, через дефис, с расширением .md. Например: new-service.md.

2. Написать контент¶

Минимальная структура страницы:

# Заголовок страницы

Краткое описание.

## Раздел 1

Текст раздела.

3. Добавить в навигацию¶

Открыть mkdocs.yml, найти блок nav: и добавить строку в нужный раздел:

- Название в меню: папка/файл.md

Без этой строки страница соберётся, но в меню не появится.

4. Проверить локально (опционально)¶

source .venv/bin/activate
mkdocs serve

Открыть http://127.0.0.1:8000 — убедиться, что страница появилась и выглядит нормально.

5. Запушить¶

git add .
git commit -m "docs: добавить статью про X"
git push

Cloudflare сам пересоберёт сайт за 1–2 минуты.

Частые ошибки¶

Страница не появилась в меню — не добавлена строка в nav: в mkdocs.yml.
Страница пустая — файл не сохранён в редакторе перед git add (белая точка на вкладке = несохранён). Сохранять всё разом: Ctrl+K S.
Текст «съело» в один код-блок — незакрытый ```. Каждый открывающий фенс должен иметь закрывающий. Чтобы показать ``` внутри страницы, обернуть во внешний фенс из четырёх кавычек.