From 1fcb989225d9c3261f63d845198326d7a9d036e4 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 7 Aug 2017 13:53:56 -0700 Subject: [PATCH 1/4] Add versioning document --- docs/versioning.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/versioning.md diff --git a/docs/versioning.md b/docs/versioning.md new file mode 100644 index 0000000000..3ba07bf7a7 --- /dev/null +++ b/docs/versioning.md @@ -0,0 +1,53 @@ +--- +id: versioning +title: Versioning Documentation +--- + +## Overview + +Docusaurus has built-in versioning features to allow users to maintain different sets of documentation for the different versions of their projects. Users can use a script to cut a version of their documents from the current ones in the `docs` folder. This will preserve these docs as docs for a specified version, and users can continue updating files in the `docs` folder to reflect the latest version of their projects. + +## How to Create New Versions + +Add the following script to your `package.json` file: + +```json +... +"scripts": { + "version": "docusaurus-version" +}, +... +``` + +Run the script with a command line argument of the version you wish to create. + +```bash +npm run version 1.0.0 +``` + +This will preserve all documents currently in the `docs` folder and make them available as documents for version `1.0.0`. + +Now, version `1.0.0` is considered the latest release version for your project, and the site will display the version number next to the title in the header. + +Documents in the `docs` folder will be considered part of version `next` and they would be available, for example, at the url `docs/next/doc1.html`. Documents from the latest version use the url `docs/doc1.html`. + +Running the script again with `npm run version 2.0.0` will create a version `2.0.0` which is now the most recent. Documents from version `1.0.0` will use the url `docs/1.0.0/doc1.html` while `2.0.0` will use `docs/doc1.html`. + + +## Versioning Patterns + +Users can create version numbers with whatever format they wish and a new version can be created with any version number as long as it does not match an existing version. Version ordering is determined by the order in which versions are created, independently of how they are numbered. + +## Storing Files for Each Version + +Versioned documents are placed into a `versioned_docs/version-${version}` folder inside of `website`. The front matter for each versioned doc is altered by appending `"version-${version}-"` to the id and by adding an `original_id` field. Versioned sidebars are copied into the `versioned_sidebars` folder inside `website` and are named as `version-${version}-sidebar.json`. If you wish to change the documentation for a past version, you can access the files for that respective version. + +## Fallback Functionality + +Only files in the `docs` folder and sidebar files that differ from those of the latest version will get copied each time a new version is specified. If there is no change across versions, Docusaurus will use the file from the latest version with that file. + +Ex: A document with the original id `doc1` exists for the latest version, `1.0.0`, and has the same content as the document with the id `doc1` in the `docs` folder. When a new version `2.0.0` is created, the file for `doc1` will not be copied into `versioned_docs/version-2.0.0/`. There will still be a page for `docs/2.0.0/doc1.html`, but it will use the file from version `1.0.0`. + +## Versioning and Translations + +If you wish to use versioning and translations features, the `crowdin.yaml` file should be set up to upload and download versioned documents to and from Crowdin for translation. Translated, versioned files will go into the folder `translated_docs/${language}/version-${version}/`. For more information, check out the [translations guide](translation.md). From 94f78f9321332544b9a60e91eb0b666f7b8c7d3e Mon Sep 17 00:00:00 2001 From: Frank Li Date: Mon, 7 Aug 2017 14:02:50 -0700 Subject: [PATCH 2/4] Change title versioning document title --- docs/versioning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/versioning.md b/docs/versioning.md index 3ba07bf7a7..b3cfca6599 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -1,6 +1,6 @@ --- id: versioning -title: Versioning Documentation +title: Documentation Versioning --- ## Overview From 483bc205131c5fbbf05ade5252f02abd1b06c459 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Tue, 8 Aug 2017 11:20:45 -0700 Subject: [PATCH 3/4] Update versioning doc --- docs/versioning.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/versioning.md b/docs/versioning.md index b3cfca6599..f04724d873 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -1,11 +1,9 @@ --- id: versioning -title: Documentation Versioning +title: Versioning --- -## Overview - -Docusaurus has built-in versioning features to allow users to maintain different sets of documentation for the different versions of their projects. Users can use a script to cut a version of their documents from the current ones in the `docs` folder. This will preserve these docs as docs for a specified version, and users can continue updating files in the `docs` folder to reflect the latest version of their projects. +Users can use the `version` script to cut a new documentation version based on the latest content in the `docs` folder. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` folder changes moving forward. ## How to Create New Versions @@ -19,34 +17,34 @@ Add the following script to your `package.json` file: ... ``` -Run the script with a command line argument of the version you wish to create. +Run the script with a command line argument of the version you wish to create. e.g., ```bash npm run version 1.0.0 ``` -This will preserve all documents currently in the `docs` folder and make them available as documents for version `1.0.0`. +This will preserve all documents currently in the `docs` folder and make them available as documentation for version `1.0.0`. -Now, version `1.0.0` is considered the latest release version for your project, and the site will display the version number next to the title in the header. +If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project, and the site will display the version number next to the title in the header. -Documents in the `docs` folder will be considered part of version `next` and they would be available, for example, at the url `docs/next/doc1.html`. Documents from the latest version use the url `docs/doc1.html`. +Documents in the `docs` folder will be considered part of version `next` and they are available, for example, at the url `docs/next/doc1.html`. Documents from the latest version use the url `docs/doc1.html`. -Running the script again with `npm run version 2.0.0` will create a version `2.0.0` which is now the most recent. Documents from version `1.0.0` will use the url `docs/1.0.0/doc1.html` while `2.0.0` will use `docs/doc1.html`. +Running the script again with `npm run version 2.0.0` will create a version `2.0.0`, making version 2.0.0 the most recent set of documentation. Documents from version `1.0.0` will use the url `docs/1.0.0/doc1.html` while `2.0.0` will use `docs/doc1.html`. ## Versioning Patterns -Users can create version numbers with whatever format they wish and a new version can be created with any version number as long as it does not match an existing version. Version ordering is determined by the order in which versions are created, independently of how they are numbered. +Users can create version numbers in whatever format they wish, and a new version can be created with any version number as long as it does not match an existing version. Version ordering is determined by the order in which versions are created, independently of how they are numbered. ## Storing Files for Each Version -Versioned documents are placed into a `versioned_docs/version-${version}` folder inside of `website`. The front matter for each versioned doc is altered by appending `"version-${version}-"` to the id and by adding an `original_id` field. Versioned sidebars are copied into the `versioned_sidebars` folder inside `website` and are named as `version-${version}-sidebar.json`. If you wish to change the documentation for a past version, you can access the files for that respective version. +Versioned documents are placed into `website/versioned_docs/version-${version}`, where `${version}` is the version number you supplied the `version` script. The front matter for each versioned doc is altered by appending `"version-${version}-"` to the id and by adding an `original_id` field. Versioned sidebars are copied into `website/versioned_sidebars` and are named as `version-${version}-sidebar.json`. A `website/versions.json` file is created the first time you cut a version and is used by Docusaurus to detect what versions exist. Each time a new version is added, it gets added to the `versions.json` file. If you wish to change the documentation for a past version, you can access the files for that respective version. ## Fallback Functionality Only files in the `docs` folder and sidebar files that differ from those of the latest version will get copied each time a new version is specified. If there is no change across versions, Docusaurus will use the file from the latest version with that file. -Ex: A document with the original id `doc1` exists for the latest version, `1.0.0`, and has the same content as the document with the id `doc1` in the `docs` folder. When a new version `2.0.0` is created, the file for `doc1` will not be copied into `versioned_docs/version-2.0.0/`. There will still be a page for `docs/2.0.0/doc1.html`, but it will use the file from version `1.0.0`. +For example, a document with the original id `doc1` exists for the latest version, `1.0.0`, and has the same content as the document with the id `doc1` in the `docs` folder. When a new version `2.0.0` is created, the file for `doc1` will not be copied into `versioned_docs/version-2.0.0/`. There will still be a page for `docs/2.0.0/doc1.html`, but it will use the file from version `1.0.0`. ## Versioning and Translations From 437dbee8726a254f3e901d74688b4a60bf4994e5 Mon Sep 17 00:00:00 2001 From: Frank Li Date: Tue, 8 Aug 2017 13:58:13 -0700 Subject: [PATCH 4/4] Update sidebar to include versioning doc --- website/sidebars.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/sidebars.json b/website/sidebars.json index bc832a7495..832522becd 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -8,7 +8,8 @@ "Guides": [ "navigation", "translation", - "search" + "search", + "versioning" ], "API": [ "site-config",