From d5eceb90fc21bc671e06a303693dc8df280005ec Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Fri, 12 Dec 2025 17:21:21 +0100 Subject: [PATCH 1/8] Update the `README.md` to run the website on Hugo --- README.md | 143 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 114 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index e98d8bc..7eca75c 100644 --- a/README.md +++ b/README.md @@ -2,57 +2,142 @@ 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 is configured correctly and the passphrase is stored in the keychain. + See the corresponding guide. TBD. -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: +* `_hugo-theme` – 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. +* `_hugo-site` – contains the HTML and CSS files needed only to run the + documentation locally. + +To run the documentation locally: + +1. Navigate to the `_hugo-site`. +2. Install project dependencies: + +```shell +npm install ``` -bundle exec jekyll serve + +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 ``` +## 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 `_hugo-site`. +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 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 -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. +The documentation related styles are placed inside `_hugo-theme/assets/scss`. +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 `_hugo-site/assets/scss`. They will not be available on `spine.io`. + +The `_hugo-theme/static` directory will be automatically included in the main site. + +## 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: + + ```shell + git config --global --add url."git@github.com:".insteadOf "https://github.com/" + ``` + +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 +[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 From 8cd6939638bed3a9b4ad4b5892ef4fe1a128e46f Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Fri, 12 Dec 2025 18:41:44 +0100 Subject: [PATCH 2/8] Add a guide for the major documentation release --- README.md | 10 +- SPINE_RELEASE.md | 168 +++++++++++++++++++ _hugo-theme/layouts/_shortcodes/version.html | 19 +++ 3 files changed, 194 insertions(+), 3 deletions(-) create mode 100644 SPINE_RELEASE.md create mode 100644 _hugo-theme/layouts/_shortcodes/version.html diff --git a/README.md b/README.md index 7eca75c..503e445 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ To get theme updates: 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 +## Code samples The code samples used in the framework documentation are added using the [`embed-code`][embed-code] Go subcommand. @@ -93,12 +93,16 @@ 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`](./_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`][authoring-guide] file. -# Styles and assets +## Styles and assets The documentation related styles are placed inside `_hugo-theme/assets/scss`. There are two main import files: diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md new file mode 100644 index 0000000..e17bca6 --- /dev/null +++ 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 `_hugo-theme/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//` 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 + ├── guick-start + └── _index.md +``` + +Also, each version should have its own `sidenav` config inside +the `data/docs/` directory. + +``` +data +└── docs + ├── 1 + │ └── sidenav.yml + └── 2 + └── sidenav.yml +``` + +### Release steps + +1. Create a new directory for the documentation inside the `content/docs//`. +2. Create the `sidenav.yml` inside `data/docs//` 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 `_hugo-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 `/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/_hugo-theme`. +3. Update the `_hugo-site/config/_default/hugo.toml` to make the version `2` as main. + +### URLs + +All URLs inside `content/docs//` 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: + +- `"/docs/guides/requirements/"` – for main version. +- `"/docs/2/guides/requirements/"` – for the version `2`. +- `"/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 +CoreJvm + +CoreJvm 1.9.0 +``` + +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/_hugo-theme/layouts/_shortcodes/version.html b/_hugo-theme/layouts/_shortcodes/version.html new file mode 100644 index 0000000..e4fb453 --- /dev/null +++ b/_hugo-theme/layouts/_shortcodes/version.html @@ -0,0 +1,19 @@ +{{- /* +Returns the current documentation full version name +or the full name of the provided version. + +Usage: +{{< version >}} -> 1.9.0 +{{< version "2" >}} -> 2.0.0 +*/ -}} + +{{- $wantedVersion := .Get 0 -}} +{{- $versions := site.Data.versions -}} +{{- $currentVersion := partial "functions/get-doc-version.html" . -}} +{{- $versionFullName := $currentVersion.full -}} +{{- if $wantedVersion -}} + {{- $version := index (where $versions "short" $wantedVersion) 0 -}} + {{- $versionFullName = $version.full -}} +{{- end -}} +{{- $versionFullName -}} +{{- /* Strip trailing newline. */ -}} From 7670a9627bcf46bc3557d2ce4dcbbb08eaff8164 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Fri, 12 Dec 2025 20:21:35 +0100 Subject: [PATCH 3/8] Clean up --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 503e445..f65b07b 100644 --- a/README.md +++ b/README.md @@ -38,18 +38,18 @@ The project has two directories: To run the documentation locally: -1. Navigate to the `_hugo-site`. +1. Navigate to the `_hugo-site` directory. 2. Install project dependencies: -```shell -npm install -``` + ```shell + npm install + ``` 3. Run the site locally: - -```shell -hugo server -``` + + ```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 @@ -69,7 +69,7 @@ be updated in the main `spine.io` site repository. To get theme updates: -1. Navigate to the `_hugo-site`. +1. Navigate to the `_hugo-site` directory. 2. Clean the module cache: ```shell From 9ecd620ac6c03afeb571f113e6d6e16b177ba7cc Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Mon, 15 Dec 2025 15:24:06 +0100 Subject: [PATCH 4/8] Update the folder names --- README.md | 16 ++++++++-------- SPINE_RELEASE.md | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index f65b07b..3db3f6b 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,15 @@ are working as intended. It allows making changes more convenient for authors. The project has two directories: -* `_hugo-theme` – contains the documentation files along with all the necessary +* `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. -* `_hugo-site` – contains the HTML and CSS files needed only to run the +* `site` – contains the HTML and CSS files needed only to run the documentation locally. To run the documentation locally: -1. Navigate to the `_hugo-site` directory. +1. Navigate to the `site` directory. 2. Install project dependencies: ```shell @@ -69,7 +69,7 @@ be updated in the main `spine.io` site repository. To get theme updates: -1. Navigate to the `_hugo-site` directory. +1. Navigate to the `site` directory. 2. Clean the module cache: ```shell @@ -104,7 +104,9 @@ the [`AUTHORING.md`][authoring-guide] file. ## Styles and assets -The documentation related styles are placed inside `_hugo-theme/assets/scss`. +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 @@ -115,9 +117,7 @@ There are two main import files: 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 `_hugo-site/assets/scss`. They will not be available on `spine.io`. - -The `_hugo-theme/static` directory will be automatically included in the main site. +in `site/assets/scss`. They will not be available on `spine.io`. ## Troubleshooting diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md index e17bca6..5ffefff 100644 --- a/SPINE_RELEASE.md +++ b/SPINE_RELEASE.md @@ -11,7 +11,7 @@ Release new version of the documentation This site supports documentation versioning. All links within the documentation are rendered automatically. -The versions are managed in the `_hugo-theme/data/versions.yml` file. +The versions are managed in the `docs/data/versions.yml` file. ```yml - short: "1" @@ -95,7 +95,7 @@ data item_visible: false ``` -4. Update the `_hugo-site/config/_default/hugo.toml` to make the version `2` as main. +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: @@ -113,8 +113,8 @@ 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/_hugo-theme`. -3. Update the `_hugo-site/config/_default/hugo.toml` to make the version `2` as main. +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 From fcb7c0cc7f7f992bcd1b912ed653492b6509a68b Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Mon, 15 Dec 2025 18:52:34 +0100 Subject: [PATCH 5/8] Fix typo in URL --- docs/content/docs/1/examples/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/1/examples/_index.md b/docs/content/docs/1/examples/_index.md index 8b67c16..bc7063f 100755 --- 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 From e6ce64213036cdb5103c4044acbecb163406c3cb Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Mon, 15 Dec 2025 19:26:47 +0100 Subject: [PATCH 6/8] Fix the URL --- docs/content/docs/1/guides/start-new-project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/docs/1/guides/start-new-project.md b/docs/content/docs/1/guides/start-new-project.md index d9b48c5..18a5868 100755 --- 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/ From d1da958b02946520777e5a000914ea114f53d5c2 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Tue, 16 Dec 2025 11:51:26 +0100 Subject: [PATCH 7/8] Make it possible to provide the optional `is_active` property from the parent --- docs/layouts/_partials/docs/components/sidenav/category.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/layouts/_partials/docs/components/sidenav/category.html b/docs/layouts/_partials/docs/components/sidenav/category.html index a4b1d25..b3b617c 100644 --- 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 }}
  • Date: Tue, 16 Dec 2025 13:00:17 +0100 Subject: [PATCH 8/8] Clean up --- README.md | 4 ++-- SPINE_RELEASE.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3db3f6b..cf7411e 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,7 @@ are working as intended. It allows making changes more convenient for authors. 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 is configured correctly and the passphrase is stored in the keychain. - See the corresponding guide. TBD. +5. Make sure [SSH][site-commons-ssh] is configured correctly and the passphrase is stored in the keychain. ## Running the documentation locally @@ -141,6 +140,7 @@ in `site/assets/scss`. They will not be available on `spine.io`. [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 diff --git a/SPINE_RELEASE.md b/SPINE_RELEASE.md index 5ffefff..ed6b626 100644 --- a/SPINE_RELEASE.md +++ b/SPINE_RELEASE.md @@ -53,7 +53,7 @@ content │ └── _index.md └── 2 ├── client-libs - ├── guick-start + ├── quick-start └── _index.md ```