feat: add option to sort items in properties shortcode (#527)

BREAKING CHANGE: To enable sorting of elements in the `properties` shortcode, it was necessary to change the structure of the properties file. Due to this change, the `properties` object now requires a list of maps instead of a map. A [sample file](https://raw.githubusercontent.com/thegeeklab/hugo-geekdoc/main/exampleSite/data/properties/demo.yaml) can be found in the repository.

3 files changed, 38 insertions, 13 deletions

diff --git a/exampleSite/content/en/shortcodes/propertylist.md b/exampleSite/content/en/shortcodes/propertylist.md
index fca3bb3..d00c13c 100644
--- a/exampleSite/content/en/shortcodes/propertylist.md
+++ b/exampleSite/content/en/shortcodes/propertylist.md
@@ -2,11 +2,21 @@
 title: Properties
 ---
 
-The property list shortcode creates a custom HTML description list that can be used to display properties or variables and general dependent information. The shortcode requires a data file in `data/properties/`, e.g. `data/properties/demo.yaml`, where the filename must be passed to the `name` attribute of the property list shortcode.
+The property list shortcode creates a custom HTML description list that can be used to display properties or variables and general dependent information. The shortcode requires a data file in `data/properties/`, e.g. `data/properties/demo.yaml`.
+
+## Attributes
+
+| Name             | Description                                            | default   |
+| ---------------- | ------------------------------------------------------ | --------- |
+| name             | name of the file from the `data/properties/` directory | undefined |
+| sort (optional)  | field name to use for sorting                          | undefined |
+| order (optional) | sort order, only applied if `sort` is set              | `asc`     |
+
+## Usage
 
 <!-- prettier-ignore-start -->
 ```tpl
-{{</* propertylist name=demo */>}}
+{{</* propertylist name=demo (sort=name) (order=[asc|desc]) */>}}
 ```
 <!-- prettier-ignore-end -->
 
@@ -20,4 +30,8 @@ The supported attributes can be taken from the following example:
 
 ## Example
 
-{{< propertylist name=demo >}}
+<!-- prettier-ignore-start -->
+<!-- spellchecker-disable -->
+{{< propertylist name=demo sort=name order=asc >}}
+<!-- spellchecker-enable -->
+<!-- prettier-ignore-end -->
diff --git a/exampleSite/data/properties/demo.yaml b/exampleSite/data/properties/demo.yaml
index b220b00..75a1770 100644
--- a/exampleSite/data/properties/demo.yaml
+++ b/exampleSite/data/properties/demo.yaml
@@ -1,11 +1,11 @@
 ---
 properties:
-  prop1:
+  - name: prop1
     type: string
     description: Dummy description of the prop1 string property.
     required: true
 
-  prop2:
+  - name: prop2
     type: int
     defaultValue: 10
     description:
@@ -16,7 +16,7 @@ properties:
         - tag1
         - tag2
 
-  prop3:
+  - name: prop3
     type: bool
     defaultValue: false
     description: |
@@ -27,3 +27,8 @@ properties:
 
       More description how to use this property.
     required: false
+
+  - name: a-prop
+    type: string
+    description: Property to demonstrate sorting.
+    required: true
diff --git a/layouts/shortcodes/propertylist.html b/layouts/shortcodes/propertylist.html
index eddae6d..a1cdf33 100644
--- a/layouts/shortcodes/propertylist.html
+++ b/layouts/shortcodes/propertylist.html
@@ -1,21 +1,27 @@
 {{- $name := .Get "name" -}}
+{{- $sort := .Get "sort" -}}
+{{- $order := default "asc" (.Get "order") -}}
 
 {{- if .Site.Data.properties }}
   <dl class="gdoc-props">
     {{- with (index .Site.Data.properties (split $name ".")) }}
-      {{- range $key, $value := .properties }}
+      {{- $properties := .properties }}
+      {{- with $sort }}
+        {{- $properties = (sort $properties . $order) }}
+      {{- end }}
+      {{- range $properties }}
         <dt class="flex flex-wrap align-center gdoc-props__meta">
-          <span class="gdoc-props__title">{{ $key }}</span>
-          {{- if $value.required }}
+          <span class="gdoc-props__title">{{ .name }}</span>
+          {{- if .required }}
             <span class="gdoc-props__tag warning">{{ i18n "propertylist_required" | lower }}</span>
           {{ else }}
             <span class="gdoc-props__tag tip">{{ i18n "propertylist_optional" | lower }}</span>
           {{- end }}
-          {{- with $value.type }}
+          {{- with .type }}
             <span class="gdoc-props__tag note">{{ . }}</span>
           {{- end }}
 
-          {{- with $value.tags }}
+          {{- with .tags }}
             {{- $tags := . }}
             {{- if reflect.IsMap $tags }}
               {{- $tags = (index $tags $.Site.Language.Lang) }}
@@ -27,7 +33,7 @@
         </dt>
         <dd>
           <div class="gdoc-props__description">
-            {{- with $value.description }}
+            {{- with .description }}
               {{- $desc := . }}
               {{- if reflect.IsMap $desc }}
                 {{- $desc = (index $desc $.Site.Language.Lang) }}
@@ -37,7 +43,7 @@
             {{ end }}
           </div>
           <div class="gdoc-props__default">
-            {{- with default "none" ($value.defaultValue | string) }}
+            {{- with default "none" (.defaultValue | string) }}
               <span>{{ i18n "propertylist_default" | title }}:</span>
               <span>{{ . }}</span>
             {{- end }}