From 35254fbb108defdfcc9f3ef71483e4881c6335d7 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 13:48:00 +0100 Subject: [PATCH 01/10] Remove the `external-link` to not override styles from the theme --- site/assets/scss/base/_override.scss | 30 ++-------------------------- 1 file changed, 2 insertions(+), 28 deletions(-) diff --git a/site/assets/scss/base/_override.scss b/site/assets/scss/base/_override.scss index c6febce0..d6c16017 100755 --- a/site/assets/scss/base/_override.scss +++ b/site/assets/scss/base/_override.scss @@ -41,34 +41,8 @@ a:focus { text-decoration: underline; } -a:focus {text-decoration: none;} - -a.external-link { - white-space: nowrap; - - &:after { - content: '\2192'; - font-weight: 300; - width: 8px; - height: 8px; - overflow: hidden; - text-align: right; - line-height: 6px; - text-indent: -11px; - opacity: .6; - transform: rotate(-45deg); - transition: opacity .16s ease-in; - vertical-align: super; - font-size: smaller; - text-decoration: none; - display: inline-block; - } - - &:hover { - &:after { - color: $second-brand-color; - } - } +a:focus { + text-decoration: none; } .nofloat { From 4a0bd4460df1f3800ae039ce9a1439426d903cba Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 15:52:39 +0100 Subject: [PATCH 02/10] Bump the Hugo version to fix TOC rendering when headings contain a link --- .github/workflows/gh-pages.yml | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 36cbf77b..d78775e8 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -7,7 +7,7 @@ on: - staging env: - HUGO_VERSION: 0.147.8 + HUGO_VERSION: 0.150.0 GH_USER: site-commons-machine-user jobs: diff --git a/README.md b/README.md index b317c056..9bedceb6 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ into the pages, please see the [`_code/EMBEDDING.md`](_code/EMBEDDING.md) file. 1. Install [Java JDK] version `11` to build the site. 2. 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. +3. Install [Hugo Extended][hugo-quick-start] at least version `v0.150.0` 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. From d919e4ee90cbab877b828104a1a44e0a782c4ebe Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 15:58:12 +0100 Subject: [PATCH 03/10] Add a note about permission issue --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 9bedceb6..72e46ab0 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,14 @@ Another way to run the site locally is to follow these steps: 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 +``` + ## Documentation The documentation is located in a [separate repository][documentation-repo]. From 3dc5d43044a538d7a7db5d6e0a50e4df68a8ca01 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 16:22:34 +0100 Subject: [PATCH 04/10] Add a guide on code blocks using --- AUTHORING.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 60 insertions(+), 3 deletions(-) diff --git a/AUTHORING.md b/AUTHORING.md index 3e1375ee..4b9663ae 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -13,10 +13,13 @@ This document is a guide for adding content to the [spine.io](https://spine.io) * [Main navigation](#main-navigation) * [Documentation side navigation](#documentation-side-navigation) * [Documentation “Next/Prev” buttons](#documentation-nextprev-buttons) - * [Adding code samples to the site](#adding-code-samples-to-the-site) +* [Adding code samples to the site](#adding-code-samples-to-the-site) * [Testing broken links](#testing-broken-links) - * [Cloak email](#cloak-email) - * [Note blocks](#note-blocks) +* [Cloak email](#cloak-email) +* [Note blocks](#note-blocks) +* [Code blocks](#code-blocs) + * [Code blocks using triple backticks](#1-code-blocks-using-triple-backticks) + * [Code blocks using the `highlight` shortcode](#2-code-blocks-using-the-highlight-shortcode) Table of contents generated with markdown-toc @@ -156,3 +159,57 @@ You can use only predefined classes such as: `note`, `warning`, or `lead`. The test lead block. {{% /note-block %}} ``` + +# Code blocs + +There are two ways to add code blocks with syntax highlighting. + +### 1. Code blocks using triple backticks + +Please always specify the code language to avoid problems with the layout. + +````markdown +```bash +git clone git@github.com:spine-examples/hello.git +``` +```` + +You can configure the appearance of Hugo code blocks using parameters, +as described in the official [documentation][code-fences-doc]: + +* `linenos=table` – configure line numbers and renders them in a table view. + The table view is necessary for correct copying of code. +* `hl_lines=[8,"15-17"]` – lists a set of line numbers or line number ranges + to be additionally highlighted. +* `linenostart=199` – starts the line number count from 199. + +````markdown +```java {linenos=table,hl_lines=[8,"15-17"],linenostart=199} +// ... code +``` +```` + +### 2. Code blocks using the `highlight` shortcode + +The `highlight` shortcode allows to set custom visibility options related to this project, +such as custom CSS classes, the text highlighting on the selected line, a file name bar, etc. + +```markdown +{{< highlight lang="java" params="hl_lines=10 19, linenos=table" class="hl-text-only" >}} +@BeforeEach +void sendCommand() { +... +} +{{< /highlight >}} +``` + +Where: +* `lang`. The language of the code block. +* `params`. Optional standard Hugo highlighting parameters as a string. +* `file`. An optional name of the code file to display on the code header panel. +* `class`. An optional class name that the code block will be wrapped in. + +The class `hl-text-only` is predefined and used to highlight only the text without highlighting +the entire line with background. + +[code-fences-doc]: https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences From 1f01d91d464e55c1ea5215ce692a5344775b72bb Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 17:10:19 +0100 Subject: [PATCH 05/10] Get theme updates with the PDF and code blocks --- site/go.mod | 2 +- site/go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/site/go.mod b/site/go.mod index 58016003..a3c8e91d 100644 --- a/site/go.mod +++ b/site/go.mod @@ -3,6 +3,6 @@ module github.com/SpineEventEngine/SpineEventEngine.github.io go 1.22.0 require ( - github.com/SpineEventEngine/documentation/docs v0.0.0-20251217134201-04d842c3fd36 // indirect + github.com/SpineEventEngine/documentation/docs v0.0.0-20251218160851-33669265d64b // indirect github.com/TeamDev-Ltd/site-commons v0.0.0-20251202150534-a795438915ff // indirect ) diff --git a/site/go.sum b/site/go.sum index d22a3826..c69e6268 100644 --- a/site/go.sum +++ b/site/go.sum @@ -1,4 +1,4 @@ -github.com/SpineEventEngine/documentation/docs v0.0.0-20251217134201-04d842c3fd36 h1:DNwC/NGdu7h44/QOJCfJZlfh/jPKNcKufFxY6eK6+90= -github.com/SpineEventEngine/documentation/docs v0.0.0-20251217134201-04d842c3fd36/go.mod h1:0lSB4kPZY9Qk429mepYiraNIEucYDIwiNVhJ3Wn3gKo= +github.com/SpineEventEngine/documentation/docs v0.0.0-20251218160851-33669265d64b h1:wPjKJZKABS8x16y8wx8K/+xtBezhnceV1Q5sfdqiu7g= +github.com/SpineEventEngine/documentation/docs v0.0.0-20251218160851-33669265d64b/go.mod h1:0lSB4kPZY9Qk429mepYiraNIEucYDIwiNVhJ3Wn3gKo= github.com/TeamDev-Ltd/site-commons v0.0.0-20251202150534-a795438915ff h1:8kjfGJhf6LeS+IlK9NRktxtcv6O/WDneBuQD3QLPGIs= github.com/TeamDev-Ltd/site-commons v0.0.0-20251202150534-a795438915ff/go.mod h1:atDeksDWBzsIidpW6Ivz2yYHwp2JPa1i1KXIxkctQ3c= From a0b9f497053d32f48252be0b1f8d887d0632403c Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 17:23:37 +0100 Subject: [PATCH 06/10] Clean up --- AUTHORING.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/AUTHORING.md b/AUTHORING.md index 4b9663ae..34b6c857 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -177,7 +177,7 @@ git clone git@github.com:spine-examples/hello.git You can configure the appearance of Hugo code blocks using parameters, as described in the official [documentation][code-fences-doc]: -* `linenos=table` – configure line numbers and renders them in a table view. +* `linenos=table` – configures line numbers and renders them in a table view. The table view is necessary for correct copying of code. * `hl_lines=[8,"15-17"]` – lists a set of line numbers or line number ranges to be additionally highlighted. @@ -204,10 +204,11 @@ void sendCommand() { ``` Where: -* `lang`. The language of the code block. -* `params`. Optional standard Hugo highlighting parameters as a string. -* `file`. An optional name of the code file to display on the code header panel. -* `class`. An optional class name that the code block will be wrapped in. + +* `lang` – the language of the code block. +* `params` – optional standard Hugo highlighting parameters as a string. +* `file` – an optional name of the code file to display on the code header panel. +* `class` – an optional class name that the code block will be wrapped in. The class `hl-text-only` is predefined and used to highlight only the text without highlighting the entire line with background. From f959677551f36be3c45124f74bd55f7b30420042 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 18:32:15 +0100 Subject: [PATCH 07/10] Clean up `README.md` --- AUTHORING.md | 13 +++++++------ README.md | 22 +++++++++++++--------- 2 files changed, 20 insertions(+), 15 deletions(-) diff --git a/AUTHORING.md b/AUTHORING.md index 34b6c857..e45993fe 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -18,8 +18,8 @@ This document is a guide for adding content to the [spine.io](https://spine.io) * [Cloak email](#cloak-email) * [Note blocks](#note-blocks) * [Code blocks](#code-blocs) - * [Code blocks using triple backticks](#1-code-blocks-using-triple-backticks) - * [Code blocks using the `highlight` shortcode](#2-code-blocks-using-the-highlight-shortcode) + * [With triple backticks](#1-with-triple-backticks) + * [Using `highlight` shortcode](#2-using-highlight-shortcode) Table of contents generated with markdown-toc @@ -160,11 +160,11 @@ The test lead block. {{% /note-block %}} ``` -# Code blocs +# Code blocks There are two ways to add code blocks with syntax highlighting. -### 1. Code blocks using triple backticks +### 1. With triple backticks Please always specify the code language to avoid problems with the layout. @@ -189,7 +189,7 @@ as described in the official [documentation][code-fences-doc]: ``` ```` -### 2. Code blocks using the `highlight` shortcode +### 2. Using `highlight` shortcode" The `highlight` shortcode allows to set custom visibility options related to this project, such as custom CSS classes, the text highlighting on the selected line, a file name bar, etc. @@ -205,7 +205,7 @@ void sendCommand() { Where: -* `lang` – the language of the code block. +* `lang` – the language syntax. See the [supported languages][syntax-highlighting-languages]. * `params` – optional standard Hugo highlighting parameters as a string. * `file` – an optional name of the code file to display on the code header panel. * `class` – an optional class name that the code block will be wrapped in. @@ -214,3 +214,4 @@ The class `hl-text-only` is predefined and used to highlight only the text witho the entire line with background. [code-fences-doc]: https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences +[syntax-highlighting-languages]: https://gohugo.io/content-management/syntax-highlighting/#languages diff --git a/README.md b/README.md index 72e46ab0..0e22cf2e 100644 --- a/README.md +++ b/README.md @@ -17,14 +17,16 @@ into the pages, please see the [`_code/EMBEDDING.md`](_code/EMBEDDING.md) file. ## Prerequisites -1. Install [Java JDK] version `11` to build the site. -2. 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.150.0` 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. -6. Install project dependencies from the `site` directory by running `npm install`. +1. JDK 8 (x86_64). +2. [Go][go] `1.12` or newer. +3. [Node.js][nodejs] `18+`. +4. [Hugo Extended][hugo-quick-start] in version `v0.150.0` or higher. +5. Access to the [`site-commons`][site-commons] repository — to download the theme. + +## Configuration + +1. Make sure [SSH][site-commons-ssh] configured correctly and the passphrase is stored in the keychain. +2. Install project dependencies from the `site` directory by running `npm install`. ## Running the site locally @@ -49,12 +51,14 @@ Another way to run the site locally is to follow these steps: 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: +the cache: ```shell hugo mod clean --all ``` +Then run the `hugo serve` again. + ## Documentation The documentation is located in a [separate repository][documentation-repo]. From bfcd3afdb5a5fbe74ce0c623860547fd7675ce4a Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 18:33:01 +0100 Subject: [PATCH 08/10] Get latest updates from `documentation` --- site/go.mod | 2 +- site/go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/site/go.mod b/site/go.mod index a3c8e91d..e746328a 100644 --- a/site/go.mod +++ b/site/go.mod @@ -3,6 +3,6 @@ module github.com/SpineEventEngine/SpineEventEngine.github.io go 1.22.0 require ( - github.com/SpineEventEngine/documentation/docs v0.0.0-20251218160851-33669265d64b // indirect + github.com/SpineEventEngine/documentation/docs v0.0.0-20251218172704-bae518144b35 // indirect github.com/TeamDev-Ltd/site-commons v0.0.0-20251202150534-a795438915ff // indirect ) diff --git a/site/go.sum b/site/go.sum index c69e6268..59b5149b 100644 --- a/site/go.sum +++ b/site/go.sum @@ -1,4 +1,4 @@ -github.com/SpineEventEngine/documentation/docs v0.0.0-20251218160851-33669265d64b h1:wPjKJZKABS8x16y8wx8K/+xtBezhnceV1Q5sfdqiu7g= -github.com/SpineEventEngine/documentation/docs v0.0.0-20251218160851-33669265d64b/go.mod h1:0lSB4kPZY9Qk429mepYiraNIEucYDIwiNVhJ3Wn3gKo= +github.com/SpineEventEngine/documentation/docs v0.0.0-20251218172704-bae518144b35 h1:ejTQ+jaJMC6Erz5wAcnTYV52VOEYtDsGYqsqmS3GqYk= +github.com/SpineEventEngine/documentation/docs v0.0.0-20251218172704-bae518144b35/go.mod h1:0lSB4kPZY9Qk429mepYiraNIEucYDIwiNVhJ3Wn3gKo= github.com/TeamDev-Ltd/site-commons v0.0.0-20251202150534-a795438915ff h1:8kjfGJhf6LeS+IlK9NRktxtcv6O/WDneBuQD3QLPGIs= github.com/TeamDev-Ltd/site-commons v0.0.0-20251202150534-a795438915ff/go.mod h1:atDeksDWBzsIidpW6Ivz2yYHwp2JPa1i1KXIxkctQ3c= From c88075ab5ee1acdc7dfe273a1710b219f0a0b0e7 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 18:37:24 +0100 Subject: [PATCH 09/10] Clean up --- AUTHORING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AUTHORING.md b/AUTHORING.md index e45993fe..ada7e17c 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -166,7 +166,8 @@ There are two ways to add code blocks with syntax highlighting. ### 1. With triple backticks -Please always specify the code language to avoid problems with the layout. +Please always specify the [language syntax][syntax-highlighting-languages] +to avoid problems with the layout. ````markdown ```bash From 3698ef1d827c3468915a9ce2454ea3f5d708a193 Mon Sep 17 00:00:00 2001 From: "julia.evseeva" Date: Thu, 18 Dec 2025 18:44:13 +0100 Subject: [PATCH 10/10] Fix the link --- AUTHORING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AUTHORING.md b/AUTHORING.md index ada7e17c..6176998e 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -17,7 +17,7 @@ This document is a guide for adding content to the [spine.io](https://spine.io) * [Testing broken links](#testing-broken-links) * [Cloak email](#cloak-email) * [Note blocks](#note-blocks) -* [Code blocks](#code-blocs) +* [Code blocks](#code-blocks) * [With triple backticks](#1-with-triple-backticks) * [Using `highlight` shortcode](#2-using-highlight-shortcode)