@@ -2,42 +2,45 @@ Release new version of the documentation
22========
33
44** Table of Contents**
5- * [ Release major version] ( #release-major -version )
5+ * [ Release new version] ( #release-new -version )
66 * [ Release steps] ( #release-steps )
77 * [ URLs] ( #urls )
88
9- ## Release major version
9+ ## Release new version
1010
1111This site supports documentation versioning. All links within the
1212documentation are rendered automatically.
1313
1414The versions are managed in the ` docs/data/versions.yml ` file.
1515
1616``` yml
17- - short : " 1"
18- full : 1.9.0
19- path : docs
17+ - version_id : " 1"
18+ label : 1.9.0
19+ content_path : docs/1
20+ route_url : docs
2021 is_main : true
2122 switcher :
2223 visible : false
2324 item_visible : false
24- - short : " 2"
25- full : 2.0.0
26- path : docs/2
25+ - version_id : " 2-0-x"
26+ label : 2.0.x
27+ content_path : docs/2-0-x
28+ route_url : docs/2-0-x
2729 switcher :
2830 visible : false
2931 item_visible : false
3032` ` `
3133
3234Where:
3335
34- * ` short` shows the major version number, which will be used primarily for the link generation.
35- * `full` the full version that will be visible in the version switcher.
36- * `path` will be used when generating links inside a documentation version.
37- * `is_main` the optional flag that marks the current main version.
36+ * ` version_id` – a major or minor version identifier used to generate the correct side navigation structure.
37+ * `label` – the full version label displayed in the version switcher and available via the `{{< version >}}` shortcode.
38+ * `content_path` – the relative path (from the `content/` directory) to the documentation files for this version.
39+ * `route_url` – the base URL used when generating internal links within this documentation version.
40+ * `is_main` – optional flag indicating that this version is the main documentation version.
3841* `switcher`:
39- * `visible` specifies whether the version switcher will be visible on the page.
40- * `item_visible` specifies whether the version will be available in the switcher dropdown.
42+ * `visible` – specifies whether the version switcher will be visible on the page.
43+ * `item_visible` – specifies whether the version will be available in the switcher dropdown.
4144
4245The `switcher` component is under development.
4346
@@ -51,7 +54,7 @@ content
5154 │ ├── client-libs
5255 │ ├── quick-start
5356 │ └── _ index.md
54- └── 2
57+ └── 2-0-x
5558 ├── client-libs
5659 ├── quick-start
5760 └── _ index.md
@@ -60,12 +63,14 @@ content
6063Also, each version should have its own `sidenav` config inside
6164the `data/docs/<version>` directory.
6265
66+ For modules with documentation, the config should live in `data/docs/<module>/<version>`.
67+
6368```
6469data
6570└── docs
6671 ├── 1
6772 │ └── sidenav.yml
68- └── 2
73+ └── 2-0-x
6974 └── sidenav.yml
7075```
7176
75802. Create the `sidenav.yml` inside `data/docs/<new-version>/` directory.
76813. Update the `data/versions.yml` config.
7782
78- For example, if you release the version `2` as the main version,
83+ For example, if you release the version `2-0-x ` as the main version,
7984 the config should be updated as follows:
80-
85+
8186 ```yml
82- - short: "1"
83- full: 1.9.0
84- path: docs # Change the path from `docs` to `docs/1`.
85- is_main: true # Change the flag to `false` or delete the line.
87+ - version_id: "1"
88+ label: 1.9.0
89+ content_path: docs/1
90+ route_url: docs # Change the route from `docs` to `docs/1`.
91+ is_main: true # Change the flag to `false` or delete the line.
8692 switcher:
8793 visible: false
8894 item_visible: false
89- - short: "2"
90- full: 2.0.0-eap # Change the version to `2.0.0` if needed.
91- path: docs/2 # Change the path from `docs/2` to `docs`.
92- is_main: false # Set `is_main` as `true`.
95+ - version_id: "2-0-x"
96+ label: 2.0.x
97+ content_path: docs/2-0-x # Change the content path to `docs` if the documentation will be copied to the root.
98+ route_url: docs/2-0-x # Change the route from `docs/2-0-x` to `docs`.
99+ is_main: false # Set `is_main` as `true`.
93100 switcher:
94101 visible: false
95102 item_visible: false
96103 ```
97104
98- 4. Update the `site/config/_default/hugo.toml` to make the version `2` as main.
99-
100- - Navigate to the end of the file to the section "Version control config".
101- - Find the `path` parameters and update as follows:
102- ```
103- path = '{/docs/1}' -> path = '{/docs/2}'
104- path = '{/docs/1/**}' -> path = '{/docs/2/**}'
105- ```
106-
107- Now the version `2` will be available at the `<domain>/docs/` URL and
108- will be opened by default.
109-
110- 5. Commit and push the new version release.
105+ 4. Commit and push the new version release.
111106
112107Get updates into the main website:
113108
0 commit comments