|
| 1 | +# Formsflow.ai Documentation |
| 2 | + |
| 3 | + |
| 4 | +### Versioning |
| 5 | + |
| 6 | +You can use the versioning CLI to create a new documentation version based on the latest content in the docs directory. That specific set of documentation will then be preserved and accessible even as the documentation in the docs directory continues to evolve. |
| 7 | + |
| 8 | +Most of the time, you don't need versioning as it will just increase your build time, and introduce complexity to your codebase. Versioning is best suited for websites with high-traffic and rapid changes to documentation between versions. If your documentation rarely changes, don't add versioning to your documentation. |
| 9 | + |
| 10 | +To better understand how versioning works and see if it suits your needs, you can read on below. |
| 11 | + |
| 12 | +## Overview |
| 13 | + |
| 14 | +``` |
| 15 | +website |
| 16 | +├── sidebars.json # sidebar for the current docs version |
| 17 | +├── docs # docs directory for the current docs version |
| 18 | +│ ├── foo |
| 19 | +│ │ └── bar.md # https://mysite.com/docs/next/foo/bar |
| 20 | +│ └── hello.md # https://mysite.com/docs/next/hello |
| 21 | +├── versions.json # file to indicate what versions are available |
| 22 | +├── versioned_docs |
| 23 | +│ ├── version-1.1.0 |
| 24 | +│ │ ├── foo |
| 25 | +│ │ │ └── bar.md # https://mysite.com/docs/foo/bar |
| 26 | +│ │ └── hello.md |
| 27 | +│ └── version-1.0.0 |
| 28 | +│ ├── foo |
| 29 | +│ │ └── bar.md # https://mysite.com/docs/1.0.0/foo/bar |
| 30 | +│ └── hello.md |
| 31 | +├── versioned_sidebars |
| 32 | +│ ├── version-1.1.0-sidebars.json |
| 33 | +│ └── version-1.0.0-sidebars.json |
| 34 | +├── docusaurus.config.js |
| 35 | +└── package.json |
| 36 | +``` |
| 37 | + |
| 38 | +The `versions.json` file is a list of version names, ordered from newest to oldest. |
| 39 | + |
| 40 | +## Terminology |
| 41 | +Note the terminology we use here. |
| 42 | +### Current version |
| 43 | +- The version placed in the ./docs folder. |
| 44 | +### Latest version / last version |
| 45 | +- The version served by default for docs navbar items. Usually has path /docs. |
| 46 | + |
| 47 | + |
| 48 | +Current version is defined by the file system location, while latest version is defined by the the navigation behavior. They may or may not be the same version! (And the default configuration, as shown in the table above, would treat them as different: current version at /docs/next and latest at /docs.) |
| 49 | + |
| 50 | +## Tutorials |
| 51 | + |
| 52 | +### Tagging a new version |
| 53 | +1. First, make sure the current docs version (the ./docs directory) is ready to be frozen. |
| 54 | +2. Enter a new version number. |
| 55 | + |
| 56 | +``` |
| 57 | +npm run docusaurus docs:version 1.1.0 |
| 58 | +``` |
| 59 | + |
| 60 | +When tagging a new version, the document versioning mechanism will: |
| 61 | + |
| 62 | +- Copy the full docs/ folder contents into a new versioned_docs/version-[versionName]/ folder. |
| 63 | +- Create a versioned sidebars file based from your current sidebar configuration (if it exists) - saved as versioned_sidebars/version-[versionName]-sidebars.json. |
| 64 | +- Append the new version number to versions.json. |
| 65 | + |
| 66 | +## Updating an existing version |
| 67 | +You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published. |
| 68 | + |
| 69 | +1. Edit any file. |
| 70 | +2. Commit and push changes. |
| 71 | +3. It will be published to the version. |
| 72 | + |
| 73 | +Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`. |
| 74 | + |
| 75 | + |
| 76 | +## Deleting an existing version |
| 77 | +You can delete/remove versions as well. |
| 78 | + |
| 79 | +1. Remove the version from versions.json. |
| 80 | + |
| 81 | +Example: |
| 82 | +``` |
| 83 | +[ |
| 84 | + "2.0.0", |
| 85 | + "1.9.0", |
| 86 | +- "1.8.0" |
| 87 | +] |
| 88 | +``` |
| 89 | +1. Delete the versioned docs directory. Example: versioned_docs/version-1.8.0. |
| 90 | +2. Delete the versioned sidebars file. Example: versioned_sidebars/version-1.8.0-sidebars.json. |
0 commit comments