55 lines
2.8 KiB
Markdown
55 lines
2.8 KiB
Markdown
# Документация к проекту
|
|
|
|
Бойлерплейт для документации на базе [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
|