Миграция на zensical, актуализация под iptvc после рефакторинга

2026-07-22 01:11:07 +08:00
parent 7d61aadc5d
commit 8d0f3ebcce
665 changed files with 7626 additions and 922 deletions
@@ -0,0 +1,103 @@
+---
+icon: material/book-cog-outline
+---
+
+# :material-book-cog-outline: Сборка документации
+
+## Стилистика и правила оформления
+
+Все исходники хранятся в директории `content/` в формате **Markdown** (формат файлов `.md`).
+
+Структура проекта и его конфигурация описываются в файле `mkdocs.yml` в корне репозитория.
+
+Структура исходных файлов документации и содержание должны быть согласованными.
+
+Все ссылки на соседние страницы и изображения должны быть относительными.
+
+**Каждое предложение должно быть на одной строке.**
+Это даёт более наглядную разницу (diff) в тексте при работе с git.
+
+Абзацы и списки должны отделяться 1 пустой строкой до и после.
+
+Допустимо использовать любые стилистические возможности темы **Material for MkDocs** и самого **mkdocs**, но не следует визуально перегружать текст.
+Документацию по ним см. по ссылкам ниже.
+
+## Добавление изображений
+
+**Все изображения хранятся в директории `_assets/` рядом с документом.**
+
+Общая суть такова:
+
+* чем больше размеры, тем хуже должно быть качество;
+* чем меньше размеры, тем чётче должен быть текст.
+
+Каждое изображение должно:
+
+* быть сохранено в формате jpg;
+* иметь размер неболее 150 Кб;
+* быть сжатым с качеством 65-80% от исходного;
+* быть размером до 1500 px по наибольшей стороне.
+
+Если на изображении есть текст, он должен оставаться различимым и читаемым.
+
+Но если на изображении есть любые конфиденциальные данные и его невозможно кадрировать без потери смысла, то их необходимо скрыть.
+
+Хорошей практикой будет использовать спойлеры для скрытия больших и/или идущих подряд нескольких изображений, например:
+
+```
+Совершенно любой текст, lorem ipsum dolor sit amet.
+Совершенно любой текст, lorem ipsum dolor sit amet.
+
+??? quote "В этом спойлере несколько больших картинок"
+    ![Подпись-плейсхолдер1](_assets/example1.jpg)
+    ![Подпись-плейсхолдер2](_assets/example2.jpg)
+
+Продолжение текста, lorem ipsum dolor sit amet.
+Продолжение текста, lorem ipsum dolor sit amet.
+```
+
+Эти простые правила позволят поддерживать репозиторий достаточно компактным, а страницы делать комфортными для чтения, экономя трафик для мобильных устройств.
+
+## Стек
+
+* make
+* [docker](https://docker.com)
+* [mkdocs](https://www.mkdocs.org/)
+* [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material)
+    * <https://squidfunk.github.io/mkdocs-material>
+    * <https://squidfunk.github.io/mkdocs-material/reference/admonitions/>
+    * <https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/>
+
+## Запуск mkdocs в контейнере
+
+```
+make live
+```
+
+Перегенерирует документацию на лету сразу после сохранения файлов.
+
+Документацию в реальном времени можно просматривать по адресу [localhost:3000](http://localhost:3000).
+
+## Генерация статического сайта
+
+```
+make site
+```
+
+Генерирует статические файлы, которую можно версионировать, хранить,деплоить отдельно или просматривать на ПК через браузер.
+
+Готовый скомпилированный статический сайт с документацией находится в директории `site/`.
+
+## Генерация docker-образа 
+
+```
+make image
+```
+
+Собирает docker-образ на основе nginx, генерируя перед этим статический сайт.
+
+Запустить контейнер из этого образа по адресу [localhost:3001](http://localhost:3001) можно командой:
+
+```
+make run
+```