ENT-8966: Replaced Jekyll with Hugo documentation builder (3.24)

.github/workflows/bump-hugo-version.yml

@@ -0,0 +1,42 @@
+name: Hugo version update
+
+on:
+  schedule:
+    - cron: "0 0 * * 0" #perform every sunday's night
+  workflow_dispatch:    
+
+jobs:
+  update_hugo_version:
+    if: github.repository_owner == 'cfengine' || github.repository_owner == 'mendersoftware' || github.repository_owner == 'NorthernTechHQ'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Fetch latest Hugo release info
+      id: fetch_hugo_version
+      run: |
+        release_info=$(curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest)
+        version=$(echo "$release_info" | jq -r '.tag_name' | sed 's/v//')
+        # download checksums and find checksum of hugo_${version}_Linux-64bit.tar.gz
+        checksum=$( curl -sSL https://github.com/gohugoio/hugo/releases/download/v${version}/hugo_${version}_checksums.txt | grep hugo_${version}_Linux-64bit.tar.gz |  grep -oE "[a-z0-9]{64}")
+        echo "version=$version" >> $GITHUB_OUTPUT
+        echo "checksum=$checksum" >> $GITHUB_OUTPUT
+
+    - name: Update install_hugo.sh
+      run: |
+        sed -i "s|https://github.com/gohugoio/hugo/releases/download/v.*_Linux-64bit.tar.gz|https://github.com/gohugoio/hugo/releases/download/v${{ steps.fetch_hugo_version.outputs.version }}/hugo_${{ steps.fetch_hugo_version.outputs.version }}_Linux-64bit.tar.gz|" generator/build/install_hugo.sh
+        sed -i "s/.*sha256sum.*/RUN echo \"${{ steps.fetch_hugo_version.outputs.checksum }}  hugo.tar.gz\" | sha256sum -c/" generator/build/install_hugo.sh
+    - name: Create Pull Request
+      uses: cfengine/create-pull-request@v7
+      with:
+        commit-message: Upgraded Hugo version to ${{ steps.fetch_hugo_version.outputs.version }}
+        title: Upgraded Hugo version to ${{ steps.fetch_hugo_version.outputs.version }}
+        body: |
+          This PR updates the version of Hugo used in the generator/build/install_hugo.sh to ${{ steps.fetch_hugo_version.outputs.version }}.
+        reviewers: |
+          aleksandrychev
+
+        branch: hugo-version-update-${{ steps.fetch_hugo_version.outputs.version }}
+        sign-commits: true

README.md

@@ -223,18 +223,14 @@ Note: Do not use markdown files prefixed with `.`. They are not picked up by the
 
 Additional META tags you should set are:
 
-    layout: default
-
-Leave this as `default`.
-
     title: "The Title"
 
 The title of the page. Quoting is only necessary if the title contains YAML
 keywords (like "on").
 
-    published: true|false
+    hidden: true
 
-Pages that set this tag to `false` will not be part of the navigation structure.
+Pages that set this tag to `true` will not be part of the navigation structure.
 The HTML content will however be generated.
 
     tags: [list, of, tags with space, all lowercase]
@@ -326,10 +322,10 @@ With single backticks, this would link to the documentation of the `meta` attrib
 ### Custom macros
 
 The documentation generator will pre-process the markdown content
-before passing it to Jekyll for the rendering. The pre-processor
+before passing it to Hugo for the rendering. The pre-processor
 understands and replaces the macros. Macros all have the form
 
-`[%CFEngine_MACRO(parameters)%]`
+`{{< CFEngine_MACRO(parameters) >}}`
 
 and need to be used as a separate line, as the entire line will be
 replaced by the pre-processor.
@@ -350,11 +346,11 @@ are skipped.
 The generator searches for `filename` in the `core/examples`
 subdirectory of WKRDIR.
 
-- `[%CFEngine_include_example(filename)%]`
+- `{{< CFEngine_include_example(filename) >}}`
 
 Injects the code from `filename`.
 
-- `[%CFEngine_include_snippet(filename, begin_rx, end_rx [optional])%]`
+- `{{< CFEngine_include_snippet(filename, begin_rx, end_rx [optional]) >}}`
 
 Searches `filename` for the first line that matches the regular
 expression `begin_rx`, and injects all lines as a code block from
@@ -364,7 +360,7 @@ omitted, all lines until the end of the file will be injected.
 If the line that matches the regular expression is a comment, then
 it is excluded from the quote, otherwise it is included.
 
-- `[%CFEngine_include_markdown(filename, begin_rx, end_rx [optional])%]`
+- `{{< CFEngine_include_markdown(filename, begin_rx, end_rx [optional]) >}}`
 
 Searches `filename` for the first line that matches the regular
 expression `begin_rx`, and injects all lines **verbatim** from there
@@ -373,7 +369,7 @@ all lines until the end of the file will be injected.
 
 #### Documenting policy libraries
 
-- `[%CFEngine_library_include(filename)%]`
+- `{{< CFEngine_library_include(filename) >}}`
 
 Parses the JSON version of the CFEngine policy in `filename` and generates
 documentation from it.
@@ -415,7 +411,7 @@ The following macros require the syntax map to be generated
 via `cf-promises -s` into a file `syntax_map.json` within the
 `_generated` subdirectory of the documentation generator.
 
-- `[%CFEngine_function_prototype(arg1, arg2, ...)%]`
+- `{{< CFEngine_function_prototype(arg1, arg2, ...) >}}`
 
 Renders the prototype of the function that has the same name as the
 title of the current page. Parameters `arg1` etc are used for the names
@@ -430,7 +426,7 @@ of the parameters:
 Use this before a `**Description:**` section in which the behavior of the
 function as well as the individual parameters are then explained.
 
-- `[%CFEngine_function_attributes(arg1, arg2, ...)%]`
+- `{{< CFEngine_function_attributes(arg1, arg2, ...) >}}`
 
 Renders a list of attributes for the function that has the same name as the
 title of the current page. `arg1` etc are used for the parameter names:
@@ -450,7 +446,7 @@ Document the individual parameters either directly in the `**Description:**`
 section, or as a block after using this macro. You cannot use the macro if
 individual options of option-type parameters need detailed explanation.
 
-- `[%CFEngine_promise_attribute(default)%]`
+- `{{< CFEngine_promise_attribute(default) >}}`
 
 Renders the syntax description of the current promise attribute. The current
 markdown needs to comply with the following:
@@ -471,15 +467,15 @@ level 4 header is interpreted to be the body attribute.
 
     ### attribute1
 
-    [%CFEngine_promise_attribute(default)%]
+{{< CFEngine_promise_attribute(default) >}}
 
     This will document "attribute1" of "promise_type"
 
     ### body
 
     #### attribute1
 
-    [%CFEngine_promise_attribute(default)%]
+{{< CFEngine_promise_attribute(default) >}}
 
     This will document "attribute1" of "body"
 ```
@@ -498,17 +494,17 @@ The generated markdown is:
 If a `default` parameter is provided, then a `**Default value:**` statement
 is created.
 
-- `[%CFEngine_function_table()%]`
+- `{{< CFEngine_function_table() >}}`
 
 Renders a table of built-in functions, grouped by function category.
 
-- `[%CFEngine_syntax_map(subtree)%]`
+- `{{< CFEngine_syntax_map(subtree) >}}`
 
 Renders a nested tree of CFEngine words, starting at `subtree`.
 
 #### Other macros
 
-- `[%CFEngine_redirect(target)]`
+- `{{< CFEngine_redirect(target) >}}`
 
 Injects javascript that redirects the current page to the HTML page for `target`,
 which needs to be a title or title#section combination as in regular `[text][title#section]`
@@ -518,11 +514,11 @@ links.
 
 - follow the [Policy style guide](guide/writing-and-serving-policy/policy-style.markdown)
   in examples and code snippets
-- use the appropriate lexer for syntax highlighting via Pygments
+- use the appropriate lexer for syntax highlighting via Chroma
 
   Most important are the `cf3` lexer, as well as `bash`, `console`,
-  `diff`, `shell-session` and `sql`. But Jekyll supports
-  [many more lexers](https://pygments.org/docs/lexers/)
+  `diff`, `shell-session` and `sql`. But Hugo supports
+  [many more lexers](https://gohugo.io/content-management/syntax-highlighting/#languages)
 
 - avoid custom color schemes and hand-coded HTML
 - document the example after the example code
@@ -549,7 +545,7 @@ requires a body template, then see next section).
     Longer explanation on what it does and why it is useful,
     over multiple paragraphs if necessary.
 
-    [%CFEngine_promise_attribute(default value)%]
+    {{< CFEngine_promise_attribute(default value) >}}
 
     More information about special input values.
 
@@ -585,7 +581,7 @@ body type, with the most relevant attributes set to self-explanatory values.
     Longer explanation on what this body template is used for,
     over multiple paragraphs if necessary.
 
-    [%CFEngine_promise_attribute()%]
+    {{< CFEngine_promise_attribute() >}}
 
     **Example:**
 
@@ -607,7 +603,7 @@ runnable code.
 No header necessary - there is one function per page, and the page's
 title is the name of the function.
 
-    [%CFEngine_function_prototype(parameter1, parameters2, ...)%]
+    {{< CFEngine_function_prototype(parameter1, parameters2, ...) >}}
 
     **Description:** Returns something based on `parameter1` and `parameter2`.
 
@@ -618,7 +614,7 @@ title is the name of the function.
 
     Over multiple paragraphs if necessary.
 
-    [%CFEngine_function_attributes(parameter1, parameter2)%]
+    {{< CFEngine_function_attributes(parameter1, parameter2) >}}
 
     Explain important attribute values, correlations and limitations.
 
@@ -668,9 +664,9 @@ Special variables are documented within the page of their context.
 
 ## Publishing
 
-Jekyll is used to generate the HTML pages. The toolchain is available at
+Hugo is used to generate the HTML pages. The toolchain is available at
 https://github.com/cfengine/documentation/tree/master/generator. After you compile pages,
-Jekyll will place all files into the \_site folder, without subdirectories.
+Hugo will place all files into the \_site folder.
 
 Commits in this repository trigger the documentation generator to run, which
 then updates the contents of https://docs.cfengine.com/docs/

cheatsheet.markdown

@@ -1,7 +1,6 @@
 ---
 layout: printable
 title: Markdown cheatsheet
-published: true
 sorting: 1
 alias: markdown-cheatsheet.html
 ---
@@ -502,16 +501,16 @@ Examples from cfengine/core can be rendered using the `CFEngine_include_example`
   `[\%CFEngine_include_example(class-automatic-canonificiation.cf)\%]`
 
   {% raw %}
-  [%CFEngine_include_example(class-automatic-canonificiation.cf)%]
+  {{< CFEngine_include_example(class-automatic-canonificiation.cf) >}}
   {% endraw %}
 
 ### Include snippet of text from a file
 
 Sometimes it's nice to include a snippet from another file. For example, we dynamically generate the `--help` output for each component on each doc build and that output is included on each component page.
 
-`[%CFEngine_include_snippet(cf-promises.help, [\s]*--[a-z], ^$)%]`
+`{{< CFEngine_include_snippet(cf-promises.help, [\s]*--[a-z], ^$) >}}`
 
-[%CFEngine_include_snippet(cf-promises.help, [\s]*--[a-z], ^$)%]
+{{< CFEngine_include_snippet(cf-promises.help, [\s]*--[a-z], ^$) >}}
 
 ---
 
@@ -520,7 +519,7 @@ Sometimes it's nice to include a snippet from another file. For example, we dyna
 Sometimes it's nice to include an external file
 
 <pre>
-[%CFEngine_include_markdown(masterfiles/CHANGELOG.md)%]
+{{< CFEngine_include_markdown(masterfiles/CHANGELOG.md) >}}
 </pre>
 
 #### Including chunks of policy from the MPF
@@ -571,21 +570,21 @@ If you are referring to something within UI / screenshots / buttons etc use bold
 
 ### symlink example
 
-[%CFEngine_include_snippet(masterfiles/lib/files.cf, ^body\slink_from\sln_s.*, ^##)%]
+{{< CFEngine_include_snippet(masterfiles/lib/files.cf, ^body\slink_from\sln_s.*, ^##) >}}
 
 ### Self documenting policy
 
 #### For the stdlib:
 
-[%CFEngine_library_include(lib/commands)%]
+{{< CFEngine_library_include(lib/commands) >}}
 
 #### For update.cf?
 
-[%CFEngine_library_include(update)%]
+{{< CFEngine_library_include(update) >}}
 
 #### for promises.cf?
 
-[%CFEngine_library_include(promises)%]
+{{< CFEngine_library_include(promises) >}}
 
 ## Variables
 
@@ -597,7 +596,7 @@ three dashes at the top) or in
 [\_config.yaml](https://github.com/cfengine/documentation/blob/master/generator/_config.yml)
 can be used directly within markdown.
 
-For example this is the '{{site.CFE_manuals_version}}' version of the
+For example this is the '{{< params "CFE_manuals_version" >}}' version of the
 documentation. That variable comes from \_config.yaml.
 
 Since liquid variables look a lot like mustache variables any time you want to
@@ -627,7 +626,7 @@ site.CFE_manuals_version {{ site.CFE_manuals_version }}
            "sort":"Host name",
            "filter":{
               "CFEngine version":{
-                 "not_match":"{{site.cfengine.branch}}.0"
+                 "not_match":"{{< params "cfengine.branch" >}}.0"
               }
            },
            "select":[