[Documentation]: docs theme update

.markdownlint-cli2.yaml

@@ -1,9 +1,10 @@
 config:
-  # prefer semantic line breaks over max setnence length
+  # prefer semantic line breaks over max sentence length
   line-length: false
   # tabbed code examples violate this rule
   no-space-in-code: false
   # sometimes you gotta be hacky
   no-inline-html: false
+  code-block-style: false
 
 fix: true

docs/Dockerfile

@@ -1,4 +1,4 @@
-FROM squidfunk/mkdocs-material:7.3.6
+FROM squidfunk/mkdocs-material:8.0.4
 RUN pip install \
     mkdocs-gen-files \
     mkdocs-exclude \

docs/concepts/library-development/library-configuration-file.md

@@ -18,10 +18,10 @@ Methods within steps annotated with `@Validate` will execute before the Pipeline
 For example, if a library wanted to validate a more complex use case such as ensuring a library parameter named `threshold` was greater than or equal to zero but less than or equal to 100 the following could be implemented:
 
 ``` groovy title="threshold_check.groovy"
-@Validate [1]
-void call(context){ [2]
-  if(config.threshold < 0 || config.threshold > 100){ [3]
-    error "Library parameter 'threshold' must be within the range of: 0 <= threshold <= 100" [4]
+@Validate // (1)
+void call(context){ // (2)
+  if(config.threshold < 0 || config.threshold > 100){ // (3)
+    error "Library parameter 'threshold' must be within the range of: 0 <= threshold <= 100" // (4)
   }
 }
 ```

docs/concepts/library-development/library-structure.md

@@ -15,19 +15,19 @@ The name of the directory is the library identifier used within the Pipeline Con
 
 ## Example Library Structure
 
-``` text
-exampleLibraryName [1]
-├── steps [2]
-│   └── step1.groovy [3]
+``` bash
+exampleLibraryName # (1)
+├── steps # (2)
+│   └── step1.groovy # (3)
 │   └── step2.groovy
-├── resources [4]
-│   ├── someResource.txt [5]
+├── resources # (4)
+│   ├── someResource.txt # (5)
 │   └── nested
-│       └── anotherResource.json [5]
-├── src [7]
+│       └── anotherResource.json # (6)
+├── src # (7)
 │   └── example
-│       └── Utility.groovy [8]
-└── library_config.groovy [9]
+│       └── Utility.groovy # (8)
+└── library_config.groovy # (9)
 ```
 
 1. This library would be loaded via the `exampleLibraryName` identifier in the `libraries{}` block

docs/concepts/library-development/parameterizing-libraries.md

@@ -10,10 +10,10 @@ When specifying a library to be loaded, users can pass arbitrary configurations
 
 ``` groovy title="pipeline_config.groovy"
 libraries{
-  example{ [1]
-    someField = "my value" [2]
-    nested{ [3]
-      someOtherField = 11 [4]
+  example{ // (1)
+    someField = "my value" // (2)
+    nested{ // (3)
+      someOtherField = 11 // (4)
     }
   }
 }

docs/concepts/library-development/step-aliasing.md

@@ -17,7 +17,7 @@ Static step aliases are static lists of strings to cast the step to at runtime.
 `@StepAlias` can take a `String` parameter to change the name of the step at runtime.
 
 ``` groovy title="generic.groovy"
-@StepAlias("build") [1]
+@StepAlias("build") // (1)
 void call(){
     println "running as build!"
 }
@@ -30,7 +30,7 @@ void call(){
 `@StepAlias` can also accept an array of Strings to alias the step to multiple names.
 
 ``` groovy title="generic.groovy"
-@StepAlias(["build", "unit_test"]) [1]
+@StepAlias(["build", "unit_test"]) // (1)
 void call(){
     println "running as either build or unit_test!"
 }
@@ -48,7 +48,7 @@ For example, if a library called `alias` had a step called `generic.groovy` then
 ``` groovy title="pipeline_config.groovy"
 libraries{
   alias{
-    aliases = ["build", "unit_test"] [1]
+    aliases = ["build", "unit_test"] // (1)
   }
 }
 ```
@@ -58,7 +58,7 @@ libraries{
 This `aliases` parameter can then be consumed within the dynamic step alias closure:
 
 ``` groovy title="generic.groovy"
-@StepAlias(dynamic = { return config.aliases }) [1]
+@StepAlias(dynamic = { return config.aliases }) // (1)
 void call(){
     println "running as either build or unit_test!"
 }
@@ -73,7 +73,7 @@ By default, when `@StepAlias` is present in a step file, a step with the origina
 This behavior can be overridden via the `keepOriginal` annotation parameter.
 
 ``` groovy title="generic.groovy"
-@StepAlias(value = "build", keepOriginal = true) [1]
+@StepAlias(value = "build", keepOriginal = true) // (1)
 void call(){
     println "running as either build() or generic()"
 }

docs/concepts/pipeline-templates/declarative-syntax.md

@@ -85,17 +85,17 @@ The way to bypass this in Declarative Syntax to invoke the Library Step is to in
           stages{
             stage("Example"){
               steps{
-                sh "some script" [1]
+                sh "some script" // (1)
                 script{
-                  sh "some script" [2]
+                  sh "some script" // (2)
                 }
               }
             }
           }
         }
         ```
 
-        1. This `sh` call would invoke the original Jenkins DSL Pipeline Step
-        2. This `sh` call, in the `script{}` block, would invoke the loaded JTE Library Step
+        1.  This `sh` call would invoke the original Jenkins DSL Pipeline Step
+        2.  This `sh` call, in the `script{}` block, would invoke the loaded JTE Library Step
 
 [^1]: Taken from the [Declarative Syntax](https://www.jenkins.io/doc/book/pipeline/syntax/#compare) documentation.

docs/reference/library-configuration-schema.md

@@ -7,9 +7,9 @@ This page outlines the schema for [Library Configuration Files](../concepts/libr
 ### Schema
 
 ``` groovy title="library_config.groovy"
-fields{ [1]
-  required{} [2]
-  optional{} [3]
+fields{ // (1)
+  required{} // (2)
+  optional{} // (3)
 }
 ```
 
@@ -52,25 +52,26 @@ The current options for data types to test for are:
         ``` groovy title="library_config.groovy"
         fields{
           required{
-            parameterA = String [1]
-            parameterB = Number [2]
-            parameterC = Boolean [3]
+            parameterA = String // (1)
+            parameterB = Number // (2)
+            parameterC = Boolean // (3)
           }
           optional{
-            parameterD = String [4]
-            parameterE = Boolean [5]
-            parameterF = List [6]
-            parameterG = ArrayList [7]
+            parameterD = String // (4)
+            parameterE = Boolean // (5)
+            parameterF = List // (6)
+            parameterG = ArrayList // (7)
           }
         }
         ```
-    1. ensures that `parameterA` was configured and is an instance of a String
-    2. ensures that `parameterB` was configured and is an instance of a Number
-    3. ensures that `parameterC` was configured and is an instance of a Boolean
-    4. _if_`parameterD` was configured, ensures it's a String
-    5. _if_`parameterE` was configured, ensures it's a Boolean
-    6. _if_ `parameterF` was configured, ensures it's a List
-    7. _if_ `parameterG` was configured, ensures it's an ArrayList
+
+        1. ensures that `parameterA` was configured and is an instance of a String
+        2. ensures that `parameterB` was configured and is an instance of a Number
+        3. ensures that `parameterC` was configured and is an instance of a Boolean
+        4. _if_`parameterD` was configured, ensures it's a String
+        5. _if_`parameterE` was configured, ensures it's a Boolean
+        6. _if_`parameterF` was configured, ensures it's a List
+        7. _if_ `parameterG` was configured, ensures it's an ArrayList
 
 #### Enum Validation
 
@@ -81,11 +82,12 @@ Enum validation ensures that a library parameter value is one of the options def
         ``` groovy title="library_config.groovy"
         fields{
           required{
-            parameterA = [ "a", "b", 11 ] [1]
+            parameterA = [ "a", "b", 11 ] // (1)
           }
         }
         ```
-    1. ensures that `parameterA` was configured and is set to either 'a', 'b', or 11
+
+        1. ensures that `parameterA` was configured and is set to either 'a', 'b', or 11
 
 #### Regular Expression Validation
 
@@ -96,17 +98,18 @@ Regular expression validation uses Groovy's [match operator](https://docs.groovy
         ``` groovy title="library_config.groovy"
         fields{
           required{
-            parameterA = ~/^s.*/ [1]
+            parameterA = ~/^s.*/ // (1)
           }
         }
         ```
-    1. ensures that `parameterA` starts with `s`
+
+        1. ensures that `parameterA` starts with `s`
 
 ### Nested Parameters
 
-Library parameters can be arbitrarily nested within the pipeline configuration.
+Library parameters can be arbitrarily nested within the Pipeline Configuration.
 
-For example, the following pipeline configuration would be valid to pass the `example.nestedParameter` parameter to a library named `testing`.
+For example, the following Pipeline Configuration would be valid to pass the `example.nestedParameter` parameter to a library named `testing`.
 
 === "Pipeline Configuration"
     ``` groovy title="pipeline_config.groovy"

docs/styles/Vocab/JTE/accept.txt

@@ -20,4 +20,5 @@
 [Ww]alkthroughs?
 Divio
 [Mm]arkdownlint
-md
+md
+[Ee]num

mkdocs.yml

@@ -8,6 +8,7 @@ theme:
     - navigation.tabs
     - navigation.sections
     - navigation.top
+    - content.code.annotate
 
 repo_url: https://github.com/jenkinsci/templating-engine-plugin
 
@@ -41,7 +42,8 @@ markdown_extensions:
   - abbr
   - footnotes
   - attr_list
-  - pymdownx.tabbed
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.highlight
   - pymdownx.superfences
   - toc: