Versioning
Вы можете использовать команду version, чтобы создать новую версию документации, основанную на наиболее свежем контенте, размещенном в каталоге docs. Данный специфический набор документов будет сохранен с предоставлением к нему доступа, даже если документы в каталоге docs впоследствии изменятся.
Как создавать новые версии
Выполните следующую команду для создания страницы, в которой будут перечислены все версии сайта:
yarn examples versions
Будет создан файл pages/en/versions.js.
You can edit this file, later on, to customize how you display the versions.
Добавьте следующую команду в файл 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.
Because of the way this fallback works, pages that you delete are not really deleted from the website unless you tell Docusaurus to skip fallback after a certain version. To do this, use the deletedDocs option in siteConfig.js.
Переименование существующих версий
Чтобы дать существующей версии новый номер, убедитесь, что следующая команда указана в файле 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}/. Чтобы узнать больше, обратитесь к руководству по переводу.