Versioning
Вы можете использовать команду version, чтобы создать новую версию документации, основанную на наиболее свежем контенте, размещенном в каталоге docs. Данный специфический набор документов будет сохранен с предоставлением к нему доступа, даже если документы в каталоге docs впоследствии изменятся.
Как создавать новые версии
Выполните следующую команду для создания страницы, в которой будут перечислены все версии сайта:
yarn examples versions
Будет создан файл pages/en/versions.js.
Вы можете изменить этот файл позднее, чтобы настроить способ отображения версий на вашем сайте.
Добавьте следующую команду в файл package.json, если её там нет:
...
"scripts": {
"version": "docusaurus-version"
},
...
Запустите команду с параметром, указывающим версию, которую вы желаете создать. Например:
yarn run version 1.0.0
Команда сохранит все текущие документы в каталоге docs и предоставит к ним доступ как к документации версии 1.0.0.
Если, например, вы запустите команду версионирования с аргументом 1.0.0 в качестве номера версии, версия 1.0.0 будет считаться самой последней версией для вашего проекта. Сайт будет отображать номер версии сразу после заголовка в шапке страницы. Этот номер версии будет указывать на страницу с версиями, созданную вами ранее.
Документы из каталога docs будут считаться частью версии next и будут доступны по URL, например, docs/next/doc1.html. Документы последней актуальной версии будут доступны по URL адресу docs/doc1.html.
Запустив команду снова, с другим номером версии - yarn run version 2.0.0, вы создадите версию 2.0.0, причем версия 2.0.0 станет самой последней версией вашей документации. Документы версии 1.0.0 будут доступны по URL-адресу docs/1.0.0/doc1.html, в то время как 2.0.0 по адресу docs/doc1.html.
В приведенной ниже таблице кратко представлено управление версиями Docusaurus:
| Версия | Метка | URL |
|---|---|---|
| 1.0.0 | 1.0.0 | docs/1.0.0/doc1.html |
| 1.0.1 | 1.0.1 | docs/1.0.1/doc1.html |
| 2.0.0 | current | docs/doc1.html |
master branch | next | docs/next/doc1.html |
Паттерны версионирования
Вы можете создавать номера версий в любом требуемом формате, причем новая версия может быть создана с любым номером, который не совпадает с уже существующими. Порядок версий определяется порядком их публикации, вне зависимости от их нумерации.
Хранение файлов каждой версии
Версионированные документы размещаются в каталоге вида website/versioned_docs/version-${version}, где ${version} это номер версии, предоставленный вами команде version.
Заголовки markdown в каждой версии документации изменяются путем переименовывания поля id original_id исходного документа в строку вида "version-${version}-${original_id}", которая становится актуальным значение поля id для версионированного документа.
Версионированные боковые панели копируются в каталог website/versioned_sidebars с именем вида version-${version}-sidebars.json.
Файл website/versions.json создается, когда вы в первый раз публикуете версию, затем Docusaurus использует этот файл для определения того, какие версии существуют. Каждый раз, когда добавляется новая версия, она указывается в файле versions.json.
Если вы желаете изменить документацию более ранней версии, вы можете получить доступ к её файлам.
Резервная функциональность
Каждый раз, когда вы создаете новую версию документации, копируются только те файлы из каталога docs и файлы боковой панели, которые отличаются от таковых в последней версии. Если файл в новой версии не получил каких-либо изменений, то Docusaurus будет использовать файл предыдущей версии.
Например, документ с идентификатором doc1 из последней версии 1.0.0, содержит тот же контент, что и документ с идентификатором doc1 в каталоге docs. При создании новой версии, 2.0.0, файл doc1 не будет скопирован в каталог versioned_docs/version-2.0.0/. При этом страница docs/2.0.0/doc1.html будет существовать, но будет использовать файл версии 1.0.0.
Переименование существующих версий
Чтобы дать существующей версии новый номер, убедитесь, что следующая команда указана в файле package.json:
...
"scripts": {
"rename-version": "docusaurus-rename-version"
},
...
Выполните команду в терминале, указав первым параметром текущий номер версии, а вторым параметром - новый номер версии. Например:
yarn run rename-version 1.0.0 1.0.1
Версионирование и перевод
Если вы желаете использовать функции управления версиями и переводами, файл crowdin.yaml должен быть настроен для загрузки версий документов в Crowdin и выгрузки из него переведенных файлов. Переведенные, версионированные файлы будут перемещены в каталог translated_docs/${language}/version-${version}/. Чтобы узнать больше, обратитесь к руководству по переводу.