chore: update template examples for clarity and accuracy; add documen…

…tation validation task

.github/workflows/test.yaml

@@ -25,6 +25,20 @@ jobs:
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         codecov_yml_path: .github/codecov.yml
+  documentation:
+    name: Validate documentation examples
+    runs-on: ubuntu-latest
+    steps:
+    - name: Install Go
+      uses: actions/setup-go@v5
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - name: Install Task
+      uses: arduino/setup-task@v2
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+    - name: Test documentation examples
+      run: task test-doc
   compatibility:
     name: Backward compatibility with Sprig v3 (template output)
     runs-on: ubuntu-latest

docs/registries/backward.md

@@ -31,7 +31,7 @@ The `Fail` function creates an error with a specified message and returns a `nil
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ fail "Operation failed" }} // Output: nil, error with "Operation failed"
+{{ fail "Operation failed" }} // Error with "Operation failed"
 ```
 {% endtab %}
 {% endtabs %}

docs/registries/checksum.md

@@ -24,9 +24,10 @@ SHA1sum calculates the SHA-1 hash of the input string and returns it as a hexade
 
 {% tabs %}
 {% tab title="Template Example" %}
-<pre class="language-go"><code class="lang-go"><strong>{{ sha1Sum "" }} // Output: da39a3ee5e6b4b0d3255bfef95601890afd80709
-</strong>{{ sha1Sum "Hello, World!" }} // Output: 0a0a9f2a6772942557ab5355d76af442f8f65e01
-</code></pre>
+```go
+{{ sha1Sum "" }} // Output: da39a3ee5e6b4b0d3255bfef95601890afd80709
+{{ sha1Sum "Hello, World!" }} // Output: 0a0a9f2a6772942557ab5355d76af442f8f65e01
+```
 {% endtab %}
 {% endtabs %}
 
@@ -72,8 +73,8 @@ Adler32Sum calculates the Adler-32 checksum of the input string and returns it a
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ adler32Sum "" }} // Output: 00000001
-{{ adler32Sum "Hello, World!" }} // Output: 1f9e046a
+{{ adler32Sum "" }} // Output: 1
+{{ adler32Sum "Hello, World!" }} // Output: 530449514
 ```
 {% endtab %}
 {% endtabs %}

docs/registries/conversion.md

@@ -135,7 +135,7 @@ toOctal parses a value as an octal (base 8) integer.
 ```go
 {{ 777 | toOctal }} // Output: "511"
 {{ "770" | toOctal }} // Output: "504"
-{{ true | toOctal }} // Output: "1"
+{{ true | toOctal }} // Error
 {{ "invalid" | toOctal }} // Error
 ```
 {% endtab %}
@@ -154,7 +154,7 @@ toString converts a value to a string, handling various types effectively.
 {{ 1 | toString }} // Output: "1"
 {{ 1.42 | toString }} // Output: "1.42"
 {{ true | toString }} // Output: "true"
-{{ nil | toString }} // Output: "<nil>"
+{{ .UnknownOrNil | toString }} // Output: "<nil>"
 ```
 {% endtab %}
 {% endtabs %}
@@ -176,11 +176,11 @@ toDate converts a string to a `time.Time` object based on a format specification
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ toDate "2006-01-02", "2024-05-10 11:12:42" }}
-// Output: 2024-05-10 00:00:00 +0000 UTC, nil
+{{ toDate "2006-01-02" "2024-05-10" }}
+// Output: 2024-05-10 00:00:00 +0000 UTC
 ```
 
-_This example will takes the_ `"2024-05-10 11:12:42"` _string and convert it with the layout_ `"2006-01-02"`.
+_This example will takes the_ `"2024-05-10"` _string and convert it with the layout_ `"2006-01-02"`.
 {% endtab %}
 {% endtabs %}
 
@@ -198,11 +198,11 @@ toLocalDate converts a string to a time.Time object based on a format specificat
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ "2024-09-17 11:12:42" | toLocalDate "2006-01-02" "Europe/Paris" }}
-// Output: 2024-09-17 00:00:00 +0200 CEST, nil
-{{ "2024-09-17 11:12:42" | toLocalDate "2006-01-02" "MST" }}
-// Output: 2024-09-17 00:00:00 -0700 MST, nil
-{{ "2024-09-17 11:12:42" | toLocalDate "2006-01-02" "invalid" }}
+{{ "2024-09-17" | toLocalDate "2006-01-02" "Europe/Paris" }}
+// Output: 2024-09-17 00:00:00 +0200 CEST
+{{ "2024-09-17" | toLocalDate "2006-01-02" "MST" }}
+// Output: 2024-09-17 00:00:00 -0700 MST
+{{ "2024-09-17" | toLocalDate "2006-01-02" "invalid" }}
 // Error
 ```
 {% endtab %}
@@ -225,8 +225,8 @@ Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m` and `h`.
 {% tab title="Template Example" %}
 ```go
 {{ 1 | toDuration }} // Output: 1ns
-{{ (1000.0 * 1000.0) | toDuration }} // Output: 1ms
-{{ "1m" | toDuration }} // Output: 1m
+{{ 1000.0 | toDuration }} // Output: 1µs
+{{ "1m" | toDuration }} // Output: 1m0s
 {{ "invalid" | toDuration }} // Error
 {{ (toDuration "1h30m").Seconds }} // Output: 5400
 ```
@@ -242,9 +242,10 @@ Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m` and `h`.
 {% endhint %}
 
 {% tabs %}
-{% tab title="Template Example" %}
-<pre class="language-go"><code class="lang-go"><strong>{{ "42" | atoi }} // Output: 42
-</strong></code></pre>
+{% tab title="Deprecated Template Example" %}
+```go
+{{ "42" | atoi }} // Output: 42
+```
 
 :x: No error handling
 {% endtab %}
@@ -257,9 +258,10 @@ Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m` and `h`.
 {% endhint %}
 
 {% tabs %}
-{% tab title="Template Example" %}
-<pre class="language-go"><code class="lang-go"><strong>`{{ "42" | int }} // Output: 42
-</strong></code></pre>
+{% tab title="Deprecated Template Example" %}
+```go
+{{ "42" | int }} // Output: 42
+```
 {% endtab %}
 {% endtabs %}
 
@@ -270,7 +272,7 @@ Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m` and `h`.
 {% endhint %}
 
 {% tabs %}
-{% tab title="Template Example" %}
+{% tab title="Deprecated Template Example" %}
 ```go
 {{ "42" | int64 }} // Output: 42
 ```
@@ -284,8 +286,9 @@ Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m` and `h`.
 {% endhint %}
 
 {% tabs %}
-{% tab title="Template Example" %}
-<pre class="language-go"><code class="lang-go"><strong>`{{ "42.42" | float64 }} // Output: 42.42
-</strong></code></pre>
+{% tab title="Deprecated Template Example" %}
+```go
+{{ "42.42" | float64 }} // Output: 42.42
+```
 {% endtab %}
 {% endtabs %}

docs/registries/encoding.md

@@ -25,7 +25,7 @@ The function encodes a given string into its Base64 representation, converting t
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ "Hello World" | base64Encode }} // Output: "SGVsbG8gV29ybGQ="
+{{ "Hello World!" | base64Encode }} // Output: "SGVsbG8gV29ybGQh"
 ```
 {% endtab %}
 {% endtabs %}
@@ -40,7 +40,7 @@ The function decodes a Base64 encoded string back to its original form. If the i
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ "SGVsbG8gV29ybGQ=" | base64Decode }} // Output: "Hello World"
+{{ "SGVsbG8gV29ybGQh" | base64Decode }} // Output: "Hello World!"
 ```
 {% endtab %}
 {% endtabs %}
@@ -55,7 +55,7 @@ The function encodes a given string into its Base32 representation, converting t
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ "Hello World" | base32Encode }} // Output: "JBSWY3DPEBLW64TMMQQQ===="
+{{ "Hello World!" | base32Encode }} // Output: "JBSWY3DPEBLW64TMMQQQ===="
 ```
 {% endtab %}
 {% endtabs %}
@@ -70,7 +70,7 @@ The function decodes a Base32 encoded string back to its original form. If the i
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ "JBSWY3DPEBLW64TMMQQQ====" | base32Decode }} // Output: "Hello World"
+{{ "JBSWY3DPEBLW64TMMQQQ====" | base32Decode }} // Output: "Hello World!"
 ```
 {% endtab %}
 {% endtabs %}
@@ -85,8 +85,8 @@ The function converts a JSON string into a corresponding Go data structure, enab
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ '{"name":"John", "age":30}' | fromJson }} // Output: map[name:John age:30], nil
-{{ '{\invalid' | fromJson }} // Error
+{{ "{\"name\":\"John\", \"age\":30}" | fromJson }} // Output: map[age:30 name:John]
+{{ "{\\invalid" | fromJson }} // Error
 ```
 {% endtab %}
 {% endtabs %}
@@ -101,8 +101,8 @@ The function converts a Go data structure into a JSON string, allowing the data
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ $d := dict "key1" "value1" "key2" "value2" "key3" "value3" }}
-{{ toJson $d }} // Output: {"key1":"value1","key2":"value2","key3":"value3"}, nil
+{{- $d := dict "key1" "value1" "key2" "value2" "key3" "value3" -}}
+{{ toJson $d }} // Output: {\"key1\":\"value1\",\"key2\":\"value2\",\"key3\":\"value3\"}
 ```
 {% endtab %}
 {% endtabs %}
@@ -117,7 +117,7 @@ The function converts a Go data structure into a pretty-printed JSON string, for
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ $d := dict "key1" "value1" "key2" "value2" "key3" "value3" }}
+{{- $d := dict "key1" "value1" "key2" "value2" "key3" "value3" -}}
 {{ toPrettyJson $d }} // Output: "{\n  \"key1\": \"value1\",\n  \"key2\": \"value2\",\n  \"key3\": \"value3\"\n}"
 ```
 {% endtab %}
@@ -133,8 +133,8 @@ The function converts a Go data structure into a JSON string without escaping HT
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ $d := dict "content" "<p>Hello World</p>" }}
-{{ toRawJson $d }} // Output: {"content":"<p>Hello World</p>"}
+{{- $d := dict "content" "<p>Hello World</p>" -}}
+{{ toRawJson $d }} // Output: {\"content\":\"<p>Hello World</p>\"}
 ```
 {% endtab %}
 {% endtabs %}
@@ -149,7 +149,8 @@ The function deserializes a YAML string into a Go map, allowing the structured d
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ "name: John Doe\nage: 30" | fromYAML }} // Output: map[name:John Doe age:30], nil
+
+{{ "name: John Doe\nage: 30" | fromYaml }} // Output: map[age:30 name:John Doe]
 ```
 {% endtab %}
 {% endtabs %}
@@ -164,8 +165,8 @@ The function serializes a Go data structure into a YAML string, converting the d
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ $d := dict "name" "John Doe" "age" 30 }}
-{{ $d | toYaml }} // Output: name: John Doe\nage: 30
+{{- $d := dict "name" "John Doe" "age" 30 -}}
+{{ $d | toYaml }} // Output: age: 30\nname: John Doe
 ```
 {% endtab %}
 {% endtabs %}

docs/registries/env.md

@@ -24,9 +24,10 @@ The function retrieves the value of a specified environment variable from the sy
 
 {% tabs %}
 {% tab title="Template Example" %}
-<pre class="language-go"><code class="lang-go"><strong>{{ env "INVALID" }} // Output: ""
-</strong><strong>{{ "PATH" | env }} // Output: "/usr/bin:/bin:/usr/sbin:/sbin"
-</strong></code></pre>
+```go
+{{ env "INVALID" }} // Output: ""
+{{ "PATH" | env }} // Output(will be different): "/usr/bin:/bin:/usr/sbin:/sbin"
+```
 {% endtab %}
 {% endtabs %}
 
@@ -40,7 +41,7 @@ The function replaces occurrences of `${var}` or `$var` in a string with the cor
 {% tabs %}
 {% tab title="Template Example" %}
 ```go
-{{ "Path is $PATH" | expandEnv }} // Output: "Path is /usr/bin:/bin:/usr/sbin:/sbin"
+{{ "Path is $PATH" | expandEnv }} // Output(will be different): "Path is /usr/bin:/bin:/usr/sbin:/sbin"
 ```
 {% endtab %}
 {% endtabs %}