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/AUTHORING.md b/AUTHORING.md index 3e1375ee..6176998e 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-blocks) + * [With triple backticks](#1-with-triple-backticks) + * [Using `highlight` shortcode](#2-using-highlight-shortcode) Table of contents generated with markdown-toc @@ -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 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` – 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 diff --git a/README.md b/README.md index b317c056..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.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]. 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 { diff --git a/site/go.mod b/site/go.mod index 58016003..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-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 ) diff --git a/site/go.sum b/site/go.sum index d22a3826..59b5149b 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-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=