From e87dd865067bab72d4aa9215bc4333d2de64cfbf Mon Sep 17 00:00:00 2001
From: Matthew Warman <mcwarman@gmail.com>
Date: Tue, 24 Dec 2024 06:54:55 +0000
Subject: [PATCH] docs: add regex/semver to versionFilter (#2006)

* docs: add regex/semver to versionFitler

* fix: skip any empty title
---
 assets/js/index.js                            |  2 ++
 content/en/docs/core/versionFilter.adoc       | 11 +++++++
 content/en/docs/plugins/_versionFilter.adoc   | 33 ++++++++++++++++---
 .../en/docs/plugins/resource/gitBranch.adoc   |  6 ++--
 content/en/docs/plugins/resource/gitTag.adoc  |  6 +++-
 .../docs/plugins/resource/github_release.adoc |  2 ++
 6 files changed, 53 insertions(+), 7 deletions(-)
 create mode 100644 content/en/docs/core/versionFilter.adoc

diff --git a/assets/js/index.js b/assets/js/index.js
index 15e09bb05..e1e4c6130 100644
--- a/assets/js/index.js
+++ b/assets/js/index.js
@@ -111,6 +111,7 @@ Source:
   {{ $len := (len $list) -}}
 
   {{ range $index, $element := $list -}}
+    {{ if not (eq .Title "") -}}
     index.add(
       {
         id: {{ $index }},
@@ -124,6 +125,7 @@ Source:
         content: {{ .Plain | jsonify }}
       }
     );
+    {{ end -}}
   {{ end -}}
 
   search.addEventListener('input', show_results, true);
diff --git a/content/en/docs/core/versionFilter.adoc b/content/en/docs/core/versionFilter.adoc
new file mode 100644
index 000000000..7566f0f0e
--- /dev/null
+++ b/content/en/docs/core/versionFilter.adoc
@@ -0,0 +1,11 @@
+---
+title: "Version Filter"
+description: "Allows to specify the kind of version retrieved from a resource and its version pattern"
+menu:
+  docs:
+    parent: "core"
+weight: 130
+toc: true
+---
+
+include::content/en/docs/plugins/_versionFilter.adoc[]
diff --git a/content/en/docs/plugins/_versionFilter.adoc b/content/en/docs/plugins/_versionFilter.adoc
index 5620e7858..8c10ea0a4 100644
--- a/content/en/docs/plugins/_versionFilter.adoc
+++ b/content/en/docs/plugins/_versionFilter.adoc
@@ -1,5 +1,3 @@
-=== VersionFilter
-
 `versionFilter` allows to specify the kind of version retrieved from a resource and its version pattern.
 Default value is "latest" as we want to retrieve the newest version from a resource.
 
@@ -7,7 +5,8 @@ Default value is "latest" as we want to retrieve the newest version from a resou
 
 If kind is set to `latest` then no need to specify the patter as we gonna retrieve the newest version from the resource.
 
-.Example
+===== Example
+
 ```
 sources:
   kubectl:
@@ -57,7 +56,8 @@ If a version doesn't respect semantic versioning, then it's not the value is jus
 
 In the process we drop any characters not respecting semantic version like in this version "v1.0.0", we drop the "v" but we can added it back using `transformers`.
 
-.example
+===== Example
+
 ```
   jenkins-wiki-exporter:
     kind: githubRelease
@@ -71,3 +71,28 @@ In the process we drop any characters not respecting semantic version like in th
         pattern: "~1.10"
 ```
 => Return the version "v1.10.3"
+
+==== regex/semver
+
+If `versionFilter.kind` is set to `regex/semver` then we can use `versionFilter.regex` to specify a regular expression to extract version numbers.
+The regular expression should return the semantic version in the first capturing group.
+We can then use `versionFilter.pattern` to specify version pattern as explained link:https://github.com/Masterminds/semver#checking-version-constraints[here]. In the process we also sort.
+If no `versionFilter.pattern` is provided then it fallback to '*' which return the newest version.
+If a extracted version doesn't respect semantic versioning, then it's not the value is just ignored.
+
+===== Example
+
+```
+sources:
+  default:
+    name: Get latest version
+    kind: githubrelease
+    spec:
+      owner: yarnpkg
+      repository: berry
+      token: '{{ requiredEnv "GITHUB_TOKEN" }}'
+      versionfilter:
+        kind: regex/semver
+        regex: "@yarnpkg/cli/(\\d*\\.\\d*\\.\\d*)"
+```
+=> Return the version "4.5.3"
diff --git a/content/en/docs/plugins/resource/gitBranch.adoc b/content/en/docs/plugins/resource/gitBranch.adoc
index fe591f724..f2371ae97 100644
--- a/content/en/docs/plugins/resource/gitBranch.adoc
+++ b/content/en/docs/plugins/resource/gitBranch.adoc
@@ -43,6 +43,10 @@ The git branch resource is a resource designed to be used with the scmID
 
 {{< resourceparameters "sources" "gitbranch" >}}
 
+=== Version Filter
+
+include::content/en/docs/plugins/_versionFilter.adoc[]
+
 == Example
 
 [source,yaml]
@@ -50,5 +54,3 @@ The git branch resource is a resource designed to be used with the scmID
 # updatecli.yaml
 {{<include "assets/code_example/docs/plugins/resources/gitbranch/updatecli.yaml">}}
 ----
-
-include::content/en/docs/plugins/_versionFilter.adoc[]
diff --git a/content/en/docs/plugins/resource/gitTag.adoc b/content/en/docs/plugins/resource/gitTag.adoc
index ca0084677..cbfb27de7 100644
--- a/content/en/docs/plugins/resource/gitTag.adoc
+++ b/content/en/docs/plugins/resource/gitTag.adoc
@@ -44,6 +44,11 @@ The gittag resource is a resource designed to be used with the scmID
 
 {{< resourceparameters "sources" "gittag" >}}
 
+
+=== Version Filter
+
+include::content/en/docs/plugins/_versionFilter.adoc[]
+
 == Example
 
 [source,yaml]
@@ -52,4 +57,3 @@ The gittag resource is a resource designed to be used with the scmID
 {{<include "assets/code_example/docs/plugins/resources/gittag/updatecli.yaml">}}
 ----
 
-include::content/en/docs/plugins/_versionFilter.adoc[]
diff --git a/content/en/docs/plugins/resource/github_release.adoc b/content/en/docs/plugins/resource/github_release.adoc
index c61ad34fa..d6d72b7b9 100644
--- a/content/en/docs/plugins/resource/github_release.adoc
+++ b/content/en/docs/plugins/resource/github_release.adoc
@@ -36,6 +36,8 @@ It's important to notice that both information are mutually exclusive.
 
 {{< resourceparameters "sources" "githubrelease" >}}
 
+=== Version Filter
+
 include::content/en/docs/plugins/_versionFilter.adoc[]
 
 **Remark**: