Skip to content

feat: set up docs versioning

Artur Sabirov requested to merge versioning into main

Данный МР добавляет селектор версий. Все изменения пока что обкатываются на стейджинге

image

Оригинальные доки

  • Список селектора md-version__list формируется из файла versions.json. Пример файла есть в МР, на стейджинге он пока написан руками.

Коммиты

  • ci: setup docs versioning
Old content

Задача

Внедрить версионирование на сайте документации Picodata.

Решение

В конфигурацию MkDocs добавлена настройка extra: version: provider: mike, которая активируют селектор версий md-version. Список селектора md-version__list формируется из файла versions.json.

Настройка site_url добавлена в конфигурацию MkDocs для корректной работы селектора версии. Без этой настройки при смене версии страницы всегда будет открываться главная страница документации, а не другая версия той же страницы.

Примеры работы селектора версий
site_url != null
Адрес страницы:
https://docs.binary.picodata.io/picodata/branch-versioning/latest/overview/glossary/#user

Адрес страницы, после выбора версии main:
https://docs.binary.picodata.io/picodata/branch-versioning/main/overview/glossary/#user
site_url == null
Адрес страницы:
https://docs.binary.picodata.io/picodata/branch-versioning/latest/overview/glossary/#user

Адрес страницы, после выбора версии main:
https://docs.binary.picodata.io/picodata/branch-versioning/main/

Версия документации по умолчанию — алиас latest.

Изменения:

  • в файл mkdocs.yml добавлены настройки site_url и extra: version: provider: mike
  • добавлены файлы:
    • versioning/index.html — индексный файл, перенаправляющий на версию по умолчанию
    • versioning/latest — алиас latest в виде символьной ссылки на версию 23.12
    • versioning/versions.json — индекс версий, соответствующий требованиям плагина mike; содержит версии 23.12 и main
  • обновлен файл .gitlab-ci.yml:
-     - mkdocs build -d site --strict
+     - mkdocs build -d site/23.12 -s
+     - mkdocs build -d site/main -s
+     - cp -r versioning/. site

See:

Коммиты

  • feat: add mike plugin
  • .gitlab-ci.yml: clone gh-pages to site
  • .gitlab-ci.yml: build versions 23.12 and main

Close #146 (closed)

Staging: https://docs.binary.picodata.io/picodata/branch-versioning/

Саморевью

  • Контент отображается корректно
  • Ссылки в контенте работоспособны и корректны
Edited by Yaroslav Dynnikov

Merge request reports