Improve README.md

README.md

@@ -16,23 +16,18 @@ 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.
 
-The code samples used on the site and in the framework documentation are added 
-using the [`embed-code`][embed-code] tool (Go version).
+## Prerequisites
 
-The code resides under the `_code` directory. For instructions on embedding the code
-into the pages, please see the [`_code/EMBEDDING.md`](_code/EMBEDDING.md) file.
+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.
 
-## Prerequisites
+## Configuration
 
-1. Install [Java JDK] version `11` to build the site.
-2. Install [Go][go] at least version `1.12`.
-3. Install [Node.js][nodejs]. Its version should be `18+`.
-4. Install [Hugo Extended][hugo-quick-start] at least version `v0.150.0` or higher.
-5. Get access to the [`site-commons`][site-commons] repository from the admins
-   to be able to download the theme.
-6. Make sure [SSH][site-commons-ssh] is configured correctly and the passphrase 
-   is stored in the keychain.
-7. Install project dependencies from the `site` directory by running `npm install`.
+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 documentation locally
 
@@ -67,12 +62,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.
+
 ## Theme updates
 
 This project uses several components from the [`site-commons`][site-commons] 
@@ -102,7 +99,7 @@ To get theme updates:
 ## Code samples
 
 The code samples used in the framework documentation are added using
-the [`embed-code`][embed-code] Go subcommand.
+the [`embed-code`][embed-code] tool (Go version).
 
 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.

docs/assets/scss/docs/modules/_article-container.scss

@@ -67,14 +67,18 @@ $article-container-min-height: 460px;
     }
 
     pre {
-      border-radius: 0 !important;
+      border-radius: 0;
 
       code {
         padding-right: var(--code-block-padding);
         padding-left: var(--code-block-padding);
       }
     }
 
+    table tr td pre {
+      border-radius: 0;
+    }
+
     .hl {
       margin: 0 calc(var(--code-block-padding) * -1);
       padding: 0 var(--code-block-padding);
@@ -84,7 +88,7 @@ $article-container-min-height: 460px;
   li {
     .highlight {
       > .chroma {
-        border-radius: $code-block-border-radius !important;
+        border-radius: $code-block-border-radius;
         margin-left: unset;
         margin-right: unset;
 

docs/layouts/_shortcodes/highlight.html

@@ -4,7 +4,8 @@
 the simple code block without layout changes.
 
 Parameters:
-  * `lang`. The language of the code block.
+  * `lang`. The language syntax. See the supported languages here
+            https://gohugo.io/content-management/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.