Перевод на zensical и актуализация

2026-07-11 15:09:32 +08:00
parent 7ec67ef918
commit 82a98edf00
18 changed files with 1771 additions and 874 deletions
@@ -1,7 +1,54 @@
-# Пример документации к проекту
+# Документация к проекту

-* `make live` -- запуск в режиме живой перезагрузки для отладки
-* `make site` -- генерация статического сайта
-* `make image` -- генерация docker-образа
-* `make run` -- запуск контейнера из docker-образа
-* `make help` -- справка по командам
+Бойлерплейт для документации на базе [Zensical](https://zensical.org) — системы документации, построенной на MkDocs Material.
+
+## Возможности
+
+- Live-предпросмотр с автоматической перезагрузкой
+- Сборка статического сайта в Docker-образ на базе nginx
+- Светлая и тёмная темы оформления
+- Расширенный Markdown: врезки, вкладки, гриды, сноски, иконки
+- Валидация ссылок и якорей при сборке
+- Поддержка сниппетов и переиспользуемых блоков
+- Кастомные inline-бейджи через `inline_badges.py`
+
+## Структура проекта
+
+```
+content/          — исходные страницы документации (.md)
+snippets/         — переиспользуемые блоки markdown
+overrides/        — кастомизация темы: иконки, шаблоны, стили
+zensical.toml     — конфигурация проекта
+inline_badges.py  — плагин inline-бейджей
+Dockerfile        — многоэтапная сборка: zensical build → nginx
+Makefile          — команды для разработки и деплоя
+```
+
+## Быстрый старт
+
+### Требования
+
+- [Docker](https://docs.docker.com/get-docker/)
+
+### Команды
+
+| Команда      | Описание                                                        |
+| ------------ | --------------------------------------------------------------- |
+| `make live`  | Запуск в режиме живой перезагрузки на `http://localhost:8000`   |
+| `make site`  | Генерация статического сайта (с валидацией ссылок и якорей)     |
+| `make image` | Сборка Docker-образа                                            |
+| `make run`   | Запуск контейнера на `http://localhost:8001`                    |
+| `make push`  | Загрузка Docker-образа в реестр                                 |
+| `make help`  | Справка по командам (по умолчанию)                              |
+
+## Разработка
+
+Для локальной отладки используйте `make live` — откройте `http://localhost:8000` после запуска контейнера.
+
+Для проверки сборки без предупреждений используйте `make site`.
+
+Подробности о форматировании и стиле — в [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Лицензия
+
+MIT License