SpineEventEngine · JuliaEvseeva · Dec 16, 2025 · Dec 12, 2025 · Dec 12, 2025 · Dec 12, 2025
diff --git a/README.md b/README.md
@@ -2,57 +2,146 @@
 
 This repository serves for three purposes:
 
-1. The [Wiki](https://github.com/SpineEventEngine/documentation/wiki) provides documentation for developers contributing to the framework, Commiters.
+1. The [Wiki][spine-wiki] provides documentation for developers contributing to the framework, Commiters.
 2. Gathering issues improving the documentation of the framework and tasks on writing articles at spine.io and other web resources.
-3. Storing documentation files that are added as a submodule to the [spine.io](https://github.com/SpineEventEngine/spine.io) repository.
+3. Storing documentation files that are added as a submodule to the [spine.io][spine-repo] repository.
 
-We have repository for the code of [spine.io](https://spine.io) site. Issues there are for improving the site features. 
+We have repository for the code of [spine.io](https://spine.io) site. 
+Issues there are for improving the site features. 
 
-Tasks for the content of the [spine.io](https://spine.io) site should belong to issues of _this_ repository.
+Tasks for the content of the [spine.io](https://spine.io) site should belong 
+to issues of _this_ repository.
 
-This repository is made to be self-sustainable in terms of editing. A fully-fledged Jekyll site
-has been set up for it. All the contents and links are working as intended. It allows making 
-changes more convenient for authors. To make it all possible this repository has its
-own `docs` folder — otherwise all links would be broken.
+This repository is made to be self-sustainable in terms of editing. 
+A fully-fledged Hugo site has been set up for it. All the contents and links 
+are working as intended. It allows making changes more convenient for authors.
 
-# Prerequisites
+## Prerequisites
 
-1. Install Ruby.
-2. Install the `bundler` tool.
-3. Install the project dependencies by running `bundle install`.
+1. Install [Go][go] at least version `1.12`.
+2. Install [Node.js][nodejs]. Its version should be `18+`.
+3. Install [Hugo Extended][hugo-quick-start] at least version `v0.145` or higher.
+4. Get access to the [`site-commons`][site-commons] repository from the admins
+   to be able to download the theme.
+5. Make sure [SSH][site-commons-ssh] is configured correctly and the passphrase is stored in the keychain.
 
-Now you should be able to run the documentation locally.
+## Running the documentation locally
 
-# Running the documentation locally
+The project has two directories:
 
-To build and launch the site on the local server:
-```
-bundle exec jekyll serve
+* `docs` – contains the documentation files along with all the necessary
+  JS and CSS files. This directory will be added to
+  `SpineEventEngine/SpineEventEngine.github.io` as a Hugo Module.
+* `site` – contains the HTML and CSS files needed only to run the
+  documentation locally.
+
+To run the documentation locally:
+
+1. Navigate to the `site` directory.
+2. Install project dependencies:
+
+   ```shell
+   npm install
+   ```
+
+3. Run the site locally:
+
+   ```shell
+   hugo server
+   ```
+
+If you receive a `permission denied` message, but you are sure that you have 
+all the rights to the [required repositories](#prerequisites), try clearing 
+the cache and run the `hugo serve` again:
+
+```shell
+hugo mod clean --all
 ```
 
-# Code samples
+## Theme updates
+
+This project uses several components from the [`site-commons`][site-commons] 
+Hugo theme.
+
+Please note that if you update a theme with any critical changes, it must also
+be updated in the main `spine.io` site repository.
+
+To get theme updates:
+
+1. Navigate to the `site` directory.
+2. Clean the module cache:
+
+   ```shell
+   hugo mod clean
+   ```
+
+3. Update the Hugo Modules:
+
+   ```shell
+   hugo mod get -u
+   ```
+
+4. Commit and push changes from `go.mod` and `go.sum` files.
+   In the `go.sum` file keep only two last records to avoid file cluttering.
+
+## Code samples
 
 The code samples used in the framework documentation are added using
-the [`embed-code`](https://github.com/SpineEventEngine/embed-code) Jekyll subcommand.
+the [`embed-code`][embed-code] Go subcommand.
 
-The code resides under the `_code` directory. For instructions on embedding the code into the pages,
-please see the [`EMBEDDING.md`](https://github.com/SpineEventEngine/spine.io/blob/master/_code/EMBEDDING.md) file.
+The code resides under the `_code` directory. For instructions on embedding 
+the code into the pages, please see the [`EMBEDDING.md`](./_code/EMBEDDING.md) file.
 
-# Authoring
+## Product release
+
+To release a new version of Spine documentation, see the [SPINE_RELEASE.md](SPINE_RELEASE.md).
+
+## Authoring
 
 For instructions on adding the content to the documentation, please see
-the [`AUTHORING.md`](https://github.com/SpineEventEngine/spine.io/blob/master/AUTHORING.md) file.
+the [`AUTHORING.md`][authoring-guide] file.
+
+## Styles and assets
+
+The documentation related styles are placed inside `docs/assets/scss`.
+The `docs` directory will be automatically added to the main site using Hugo Modules.
+
+There are two main import files:
+
+* `docs-common.scss` — contains the common styles that are also necessary for
+  the `SpineEventEngine/SpineEventEngine.github.io` repository. To not duplicate
+  global variables and layout styles, import the file in the main repository 
+  _at the top_ of the `main.scss`
+* `docs.scss` — contains styles responsible for the appearance of the documentation. 
+  Should be imported into the `main.scss` of the `spine.io` site as well.
+
+Styles needed only for running the documentation locally are located 
+in `site/assets/scss`. They will not be available on `spine.io`.
+
+## Troubleshooting
+
+1. If you are getting the terminal `prompts disabled error` when trying to get
+   theme updates, make sure you have allowed 2FA to do its job. Also if you have
+   authentication issues during submodules update. You can resolve it with this
+   command:
 
-# Styles and assets
+   ```shell
+   git config --global --add url."git@github.com:".insteadOf "https://github.com/"
+   ```
 
-Styles were placed inside the `_sass` folder. And were separated into two import files:
-- `docs.scss` — contains styles responsible for the appearance of the documentation. 
-Should be imported into the main spine.io site.
-- `docs-common.scss` — contains styles that should only be used to build this site. 
-They are responsible for the common site layout and should not be imported into 
-the main spine.io site to not override or duplicate styles there.
+2. If you are getting the `unknown revision upgrade` error when trying to get
+   theme updates, clean the module cache:
 
-The `_css`, `_favicons`, and `_fonts` have been configured not to be built in the main repository.
+   ```shell
+   hugo mod clean --all
+   ```
 
-The images should be placed inside `img/docs` folder to be automatically included in the main site 
-and avoid accidental overrides for files with the same name.
+[go]: https://go.dev/doc/install
+[nodejs]: https://nodejs.org/en/download/current
+[hugo-quick-start]: https://gohugo.io/getting-started/quick-start/#step-1-install-hugo
+[site-commons]: https://github.com/TeamDev-Ltd/site-commons
+[site-commons-ssh]: https://github.com/TeamDev-Ltd/site-commons/tree/master?tab=readme-ov-file#configure-go-to-use-ssh-for-github
+[embed-code]: https://github.com/SpineEventEngine/embed-code/tree/embed-code-go
+[authoring-guide]: https://github.com/SpineEventEngine/SpineEventEngine.github.io/blob/master/AUTHORING.md
+[spine-repo]: https://github.com/SpineEventEngine/SpineEventEngine.github.io
+[spine-wiki]: https://github.com/SpineEventEngine/documentation/wiki
diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md
@@ -0,0 +1,168 @@
+Release new version of the documentation
+========
+
+**Table of Contents**
+* [Release major version](#release-major-version)
+    * [Release steps](#release-steps)
+    * [URLs](#urls)
+
+## Release major version
+
+This site supports documentation versioning. All links within the
+documentation are rendered automatically.
+
+The versions are managed in the `docs/data/versions.yml` file.
+
+```yml
+- short: "1"
+  full: 1.9.0
+  path: docs
+  is_main: true
+  switcher:
+    visible: false
+    item_visible: false
+- short: "2"
+  full: 2.0.0
+  path: docs/2
+  switcher:
+    visible: false
+    item_visible: false
+```
+
+Where:
+
+* `short` shows the major version number, which will be used primarily for the link generation.
+* `full` the full version that will be visible in the version switcher.
+* `path` will be used when generating links inside a documentation version.
+* `is_main` the optional flag that marks the current main version.
+* `switcher`:
+    * `visible` specifies whether the version switcher will be visible on the page.
+    * `item_visible` specifies whether the version will be available in the switcher dropdown.
+
+The `switcher` component is under development.
+
+The documentation content should be created under the `content/<version>/` directory.
+Note that the current main version is also placed under its `version` directory.
+
+```
+content
+└── docs
+    ├── 1
+    │   ├── client-libs
+    │   ├── quick-start
+    │   └── _index.md
+    └── 2
+        ├── client-libs
+        ├── quick-start
+        └── _index.md
+```
+
+Also, each version should have its own `sidenav` config inside 
+the `data/docs/<version>` directory.
+
+```
+data
+└── docs
+    ├── 1
+    │   └── sidenav.yml
+    └── 2
+        └── sidenav.yml
+```
+
+### Release steps
+
+1. Create a new directory for the documentation inside the `content/docs/<new-version>/`.
+2. Create the `sidenav.yml` inside `data/docs/<new-version>/` directory.
+3. Update the `data/versions.yml` config.
+
+   For example, if you release the version `2` as the main version,
+   the config should be updated as follows:
+
+    ```yml
+    - short: "1"
+      full: 1.9.0
+      path: docs           # Change the path from `docs` to `docs/1`.
+      is_main: true        # Change the flag to `false` or delete the line.
+      switcher:
+        visible: false
+        item_visible: false
+    - short: "2"
+      full: 2.0.0-eap      # Change the version to `2.0.0` if needed.
+      path: docs/2         # Change the path from `docs/2` to `docs`.
+      is_main: false       # Set `is_main` as `true`.
+      switcher:
+        visible: false
+        item_visible: false
+    ```
+
+4. Update the `site/config/_default/hugo.toml` to make the version `2` as main.
+
+    - Navigate to the end of the file to the section "Version control config".
+    - Find the `path` parameters and update as follows:
+      ```
+      path = '{/docs/1}' -> path = '{/docs/2}'
+      path = '{/docs/1/**}' -> path = '{/docs/2/**}'
+      ```
+
+   Now the version `2` will be available at the `<domain>/docs/` URL and
+   will be opened by default.
+
+5. Commit and push the new version release.
+
+Get updates into the main website:
+
+1. Go to the [`SpineEventEngine.github.io`](https://github.com/SpineEventEngine/SpineEventEngine.github.io) 
+   repository.
+2. Get theme updates `hugo mod get -u github.com/SpineEventEngine/documentation/docs`.
+3. Update the `config/_default/hugo.toml` to make the version `2` as main.
+
+### URLs
+
+All URLs inside `content/docs/<version>/` are automatically managed
+according to the current documentation version.
+
+Use links in documentation as follows, without including a version:
+
+`[Requirements](docs/guides/requirements/)`.
+
+Please note:
+
+* All internal links **must not** start with a slash.
+* Each link should **end with a slash** to prevent unnecessary redirects.
+
+The link above will be automatically rendered as:
+
+- `"<baseurl>/docs/guides/requirements/"` – for main version.
+- `"<baseurl>/docs/2/guides/requirements/"` – for the version `2`.
+- `"<baseurl>/docs/3/guides/requirements/"` – for the version `3`.
+
+To render the current documentation full version inside API URL,
+use `{{% version %}}` shortcode:
+
+```markdown
+[CoreJvm]({{% version %}})
+
+[CoreJvm {{% version %}}]({{% get-site-data "spine.core_jvm_repo" %}}/index.html)
+```
+
+Will be rendered as:
+
+```html
+<a href="/1.9.0">CoreJvm</a>
+
+<a href="https://github.com/SpineEventEngine/core-jvm" target="_blank">CoreJvm 1.9.0</a>
+```
+
+Where:
+
+* {{% get-site-data "spine.core_jvm_repo" %}} will apply the `core_jvm_repo`
+  from the `data/spine.yml` file.
+* {{% version %}} adds the full version of the current page -> `1.9.0`, or `2.0.0`.
+
+To provide a specific version for example in FAQ or Release Notes, use:
+
+```markdown
+{{% version "1" %}}
+```
+
+It will always render the latest “full” version of `1`, for example now it is `1.9.0`.
diff --git a/docs/content/docs/1/examples/_index.md b/docs/content/docs/1/examples/_index.md
@@ -13,7 +13,7 @@ Please see the selected list of the examples with the descriptions below.
 ## Java
 
 - [Hello World]({{% get-site-data "spine.examples" %}}/hello/) — a minimal 
-  client-server solution described in the [Quick Start](docs/guick-start/) guide.
+  client-server solution described in the [Quick Start](docs/quick-start/) guide.
 - [Blog]({{% get-site-data "spine.examples" %}}/blog/) — shows server-side 
   functionality of a simple blog.
 - [Kanban]({{% get-site-data "spine.examples" %}}/kanban/) — shows orchestrating 

diff --git a/docs/content/docs/1/guides/start-new-project.md b/docs/content/docs/1/guides/start-new-project.md
@@ -269,4 +269,4 @@ Opt for smaller, fine-graded Pull Requests instead of cluttered and complicated
 [EventStorming]: https://eventstorming.com "Learn more about EventStorming"
 [UbiquitousLanguage]: https://martinfowler.com/bliki/UbiquitousLanguage.html "Learn more about the Ubiquitous Language"
 [ReactiveDDD]: https://www.infoq.com/presentations/reactive-ddd/ "Check out the Reactive DDD presentation"
-[VaughnVernon]: https://vaughnvernon.co/
+[VaughnVernon]: https://vaughnvernon.com/
diff --git a/docs/layouts/_partials/docs/components/sidenav/category.html b/docs/layouts/_partials/docs/components/sidenav/category.html
@@ -26,11 +26,12 @@
 
 {{ $page := .page_context }}
 {{ $item := .item_context }}
+{{ $isActive := .is_active | default false }}
 
 {{ $currentCategory := partial "functions/get-doc-category.html" $page }}
 {{ $categoryKey := $item.key }}
 {{ $id := print $categoryKey "-category" }}
-{{ $isActive := eq $currentCategory $categoryKey }}
+{{ $isActive = or (eq $currentCategory $categoryKey) $isActive }}
 
 <li>
     <span class="sidenav-link tree-title {{ if not $isActive }}collapsed{{ end }}"