Документация

Документация лежит в docs/ и собирается через Zensical. Основная версия - русская: она открывается по корневому адресу сайта. Английская версия лежит отдельно в /en/.

Для публикации на GitHub Pages есть отдельные конфиги zensical.pages.toml и zensical.pages.en.toml. Они используют те же исходники, но задают абсолютный site_url для https://ethercod3.github.io/diploma_latex/.

Локальный запуск

Собрать и запустить сайт с двумя языками:

task docs

docker compose --profile docs up docs

После запуска сайт доступен в браузере:

http://localhost:8000

task docs сначала собирает русскую версию, затем английскую, а после этого раздает статические файлы из docs-site/. После изменения Markdown-файлов или конфигов команду нужно перезапустить.

Двуязычная сборка

В обоих конфигах задан extra.alternate, поэтому при обычном task docs в интерфейсе появляется переключатель языка. Первым в списке указан русский язык.

Собрать статический сайт без запуска сервера:

task docs:build

docker compose --profile docs run --rm docs "zensical build --config-file zensical.toml && zensical build --config-file zensical.en.toml"

Собрать вариант для GitHub Pages:

task docs:build:pages

docker run --rm --entrypoint sh -v "$PWD:/data" -w /data zensical/zensical:0.0.40 -lc "zensical build --config-file zensical.pages.toml && zensical build --config-file zensical.pages.en.toml"

Остановить сервис:

task docs:down

docker compose --profile docs down

Заранее скачать Docker-образ документации:

task docs:pull

docker compose --profile docs pull docs

Образ

Для документации используется официальный образ:

zensical/zensical:0.0.40

Если меняете структуру или навигацию, сначала обновите zensical.toml для русской версии, затем внесите такие же изменения в zensical.en.toml, zensical.pages.toml и zensical.pages.en.toml.