fusing the version docs in the versions page

Signed-off-by: Joshua Fernandes <[email protected]>

docs/configure/search.md

@@ -18,7 +18,7 @@ the conditions as long as the docs are open source.
 This page contains instructions for configuring Algolia for both [open-source](#docs-and-source-code-are-open-source)
 and [closed-source](#source-code-is-not-open-source) projects.
 
-## Docs and source code are open source
+## For an open source codebase
 
 Follow these steps to configure Algolia in your project:
 
@@ -50,7 +50,7 @@ Follow these steps to configure Algolia in your project:
    Edit the `docs` index in the file to match your repository's index in Algolia.
    This workflow runs in the background and populates the index that Algolia uses to search.
 
-## Source code is not open source
+## For a close source code base
 
 If your project doesn't satisfy the [Algolia checklist](https://docsearch.algolia.com/docs/who-can-apply/),
 then you can't use Algolia for free.

docs/configure/versioning/index.md

@@ -3,28 +3,154 @@ description: Support and manage multiple documentation versions.
 sidebar_position: 1
 ---
 
-# Configure versioning
+# Configure and use versioning
 
 Docusaurus can manage multiple versions of your documentation.
 See the [Docusaurus versioning documentation](https://docusaurus.io/docs/next/versioning) for
 detailed context and instructions on managing versions.
 
-## Create a docs version
+The following instructions are for documentation that uses n versions that can be accessed like so:
+
+| Path	                               | Version        | URL                | 
+|:-----------------------------------  |:-------------  |:-------------------|
+|versioned_docs/version-22.x/hello.md  | 22.x	          | /22.x/hello        |
+|versioned_docs/version-23.x/hello.md  | 23.x (latest)  |	/hello             |
+|docs/hello.md	                       | development    |	/development/hello |
+
+:::info
+Please note that unlike Read the Docs (RTD) that versions by tags on the code base, in Docusaurus,
+every version in history is kept in the `versioned_docs` folder, so the onus is on you to remove
+older versions when required
+:::
+
+Docusaurus nomenclature is slightly different to what we use. In docusaurus, any version
+(i.e. a subfolder in `versioned_docs`) is deeemed stable; and the next version is therefore called
+`next` (the next stable version). In Consensys we follow the same for the `versioned_docs` but use the
+term `development` instead, and this can be configured in docusaurus.config.js like so, where
+the `current` version is given a `label` and `path` attribute.
+
+```js
+...
+    routeBasePath: "/",
+    path: "./docs",
+    includeCurrentVersion: true,
+    lastVersion: "23.x",
+    versions: {
+      //defaults to the ./docs folder
+      // using 'development' instead of 'next' as path
+      current: {
+        label: "development",
+        path: "development",
+      },
+      //the last stable release in the versioned_docs/version-stable
+      "23.x": {
+        label: "stable (23.x)",
+      },
+      "22.x": {
+        label: "22.x",
+      },
+    },
+...
+```
+
+## Release a new docs version
+
+### 1. Create a new version of the documentation:
+
+In the following steps, we'll release the `23.x` version of the documentation (from `22.x`) as an example.
+
+<!--tabs-->
 
-Release version 1.0 of your docs using the following command:
+# Syntax
 
 ```bash
-npm run docusaurus docs:version 1.0
+npm run docusaurus docs:version <VERSION-NUMBER>
 ```
 
-The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
+# Example
+
+```bash
+npm run docusaurus docs:version 23.x
+```
+
+<!--/tabs-->
+
+This command:
+
+- Copies the full `docs/` directory into a new `version-<VERSION-NUMBER>` directory in the `versioned_docs` directory.
+- Creates a new `versioned_sidebars/version-<VERSION-NUMBER>-sidebars.json` file.
+- Appends the new version number to the `versions.json` file.
 
 Your docs now have two versions:
 
-- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
-- `current` at `http://localhost:3000/docs/next/` for the upcoming, unreleased docs.
+- `23.x` at `http://localhost:3000/` for the version 23.x docs
+- `current` at `http://localhost:3000/next/` for the upcoming, unreleased docs.
+
+### 2. Update the `docusaurus.config.js` file to re-label these paths
+
+In `docusaurus.config.js`, under `presets` > `classic` > `docs`:
+
+- Update the `lastVersion` to the new version number.
+- Under `versions`, update the current version to the new version.
+
+For example, when releasing version `23.x` (from `23.x`), update the following section in the `docusaurus.config.js`
+file by updating the version number:
+
+```js
+presets: [
+  [
+    "classic",
+    {
+      docs: {
+        sidebarPath: require.resolve("./sidebars.js"),
+        // Set a base path separate from default /docs
+        editUrl: "https://github.com/ConsenSys/doc.teku/tree/master/",
+        routeBasePath: "/",
+        path: "./docs",
+        includeCurrentVersion: true,
+        // highlight-next-line
+        lastVersion: "23.3.x",
+        versions: {
+          //defaults to the ./docs folder
+          // using 'development' instead of 'next' as path
+          current: {
+            label: "development",
+            path: "development",
+          },
+          //the last stable release in the versioned_docs/version-23.x
+          // highlight-start
+          "23.x": {
+            label: "stable (23.x)",
+          },
+          // highlight-end
+        },
+...
+],
+
+```
+
+### 3. Update the `versions.json` file
+
+:::info
+Please remember to remove any old versions that you are not required
+:::
+
+```json
+[
+  "23.x"
+]
+```
+
+### 4. Delete the previous doc versions (if needed)
+
+If you have deleted a version in step 3, also delete the artifacts for that version. For example, if deleting version `22.x` that would mean deleting the following:
+
+1. In the `versioned_docs` directory, delete the `version-22.x` folder
+2. In the `versioned_sidebars` directory, delete the `version-22.x-sidebars.json` file.
+
+Create your pull request. You can perform a final check using the preview link generated for your PR.
 
-## Add a version dropdown
+### 5. Add a version dropdown (Do this once only when versioning is introduced)
 
 To navigate seamlessly across versions, add a version dropdown by modifying `docusaurus.config.js`
 as follows:
@@ -57,5 +183,5 @@ The docs version dropdown appears in your navbar:
 
 You can edit versioned docs in their respective folder:
 
-- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`.
+- `versioned_docs/version-23.x/hello.md` updates `http://localhost:3000/docs/hello`.
 - `docs/hello.md` updates `http://localhost:3000/docs/next/hello`.