Merge pull request #523 from SpineEventEngine/theme-update

Get the latest documentation updates and bump the Hugo version

Author: JuliaEvseeva

.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:

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-blocks)
+  * [With triple backticks](#1-with-triple-backticks)
+  * [Using `highlight` shortcode](#2-using-highlight-shortcode)
 
 <small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>
 
@@ -156,3 +159,60 @@ You can use only predefined classes such as: `note`, `warning`, or `lead`.
 The test lead block.
 {{% /note-block %}}
 ```
+
+# Code blocks
+
+There are two ways to add code blocks with syntax highlighting.
+
+### 1. With triple backticks
+
+Please always specify the [language syntax][syntax-highlighting-languages]
+to avoid problems with the layout.
+
+````markdown
+```bash
+git clone [email protected]: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` – 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.
+* `linenostart=199` – starts the line number count from 199.
+
+````markdown
+```java {linenos=table,hl_lines=[8,"15-17"],linenostart=199}
+// ... code
+```
+````
+
+### 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.
+
+```markdown
+{{< highlight lang="java" params="hl_lines=10 19, linenos=table" class="hl-text-only" >}}
+@BeforeEach
+void sendCommand() {
+...
+}
+{{< /highlight >}}
+```
+
+Where:
+
+* `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.
+
+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
+[syntax-highlighting-languages]: https://gohugo.io/content-management/syntax-highlighting/#languages

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.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.
-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
 
@@ -47,6 +49,16 @@ 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:
+
+```shell
+hugo mod clean --all
+```
+
+Then run the `hugo serve` again.
+
 ## Documentation
 
 The documentation is located in a [separate repository][documentation-repo].

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 {

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-20251218172704-bae518144b35 // indirect
 	github.com/TeamDev-Ltd/site-commons v0.0.0-20251202150534-a795438915ff // indirect
 )

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-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=