fix(QTDI-512): documentation navigation

documentation/pom.xml

@@ -28,7 +28,7 @@
   <description>Actually framework documentation, generated as a website and pushed to Github pages.</description>
 
   <properties>
-    <antora.version>3.0.1</antora.version>
+    <antora.version>3.0.3</antora.version>
 
     <!-- -Dantora.site.mode=dev-poc to test new theme -->
     <antora.dev.site.mode>dev</antora.dev.site.mode>
@@ -702,7 +702,7 @@
       <plugin>
         <groupId>org.asciidoctor</groupId>
         <artifactId>asciidoctor-maven-plugin</artifactId>
-        <version>2.2.2</version>
+        <version>2.2.6</version>
         <dependencies>
           <dependency>
             <groupId>org.asciidoctor</groupId>

documentation/src/main/antora/modules/ROOT/pages/_partials/generated_actions.adoc

@@ -156,6 +156,34 @@ Mark an action as returning a discovered schema. Its parameter MUST be a dataset
       "valid":true
     }
   ],
+  "entriesOrdered":[
+    {
+      "comment":"The column 1",
+      "errorCapable":false,
+      "metadata":false,
+      "name":"column1",
+      "nullable":false,
+      "props":{
+
+      },
+      "rawName":"column 1",
+      "type":"STRING",
+      "valid":true
+    },
+    {
+      "comment":"The int column",
+      "errorCapable":false,
+      "metadata":false,
+      "name":"column2",
+      "nullable":false,
+      "props":{
+
+      },
+      "rawName":"column 2",
+      "type":"INT",
+      "valid":true
+    }
+  ],
   "metadata":[
   ],
   "props":{
@@ -206,6 +234,34 @@ Mark a method as returning a Schema resulting from a connector configuration and
       "valid":true
     }
   ],
+  "entriesOrdered":[
+    {
+      "comment":"The column 1",
+      "errorCapable":false,
+      "metadata":false,
+      "name":"column1",
+      "nullable":false,
+      "props":{
+
+      },
+      "rawName":"column 1",
+      "type":"STRING",
+      "valid":true
+    },
+    {
+      "comment":"The int column",
+      "errorCapable":false,
+      "metadata":false,
+      "name":"column2",
+      "nullable":false,
+      "props":{
+
+      },
+      "rawName":"column 2",
+      "type":"INT",
+      "valid":true
+    }
+  ],
   "metadata":[
   ],
   "props":{

documentation/src/main/antora/site-dev-template.yml

@@ -40,3 +40,6 @@ asciidoc:
     hide-uri-scheme: true
     icons: font
     icon-set: octicon
+antora:
+  extensions:
+    - ./supplemental-ui/extensions/siteMap.js

documentation/src/main/antora/site-template.yml

@@ -95,3 +95,6 @@ asciidoc:
     hide-uri-scheme: true
     icons: font
     icon-set: octicon
+antora:
+  extensions:
+    - ./supplemental-ui/extensions/siteMap.js

documentation/src/main/antora/supplemental-ui/extensions/siteMap.js

@@ -0,0 +1,46 @@
+/**
+ *  Copyright (C) 2006-2025 Talend Inc. - www.talend.com
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+'use strict'
+
+module.exports.register = function () {
+  this.on('uiLoaded', ({ uiCatalog }) => {
+    const handlebars = this.require('handlebars')
+
+
+    /**
+     * Validates whether the given path exists in the content catalog.
+     */
+    handlebars.registerHelper('validatePath', function(pathToCheck, { data }) {
+      const { contentCatalog } = data.root
+
+      if (!contentCatalog) {
+          console.warn('Content catalog is not available.')
+          return null
+      }
+
+      const allPages = contentCatalog.getPages(({ out }) => {
+        return out !== undefined
+      })
+
+      const currentPage = allPages.some(page => page.pub.url === pathToCheck)
+      if (!currentPage) {
+          console.warn(`Path ${pathToCheck} does not exist`)
+      }
+
+      return currentPage ? pathToCheck : null
+    })
+  })
+}

documentation/src/main/antora/supplemental-ui/helpers/swapLastSegment.js

@@ -0,0 +1,59 @@
+/**
+ *  Copyright (C) 2006-2025 Talend Inc. - www.talend.com
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+'use strict';
+
+
+/*
+ * /component name/version/pagePart1/pagePart2
+ * 1 - is component
+ * 2 - is version
+ * 3+ - is page path
+*/
+const VERSIONED_SEGMENTS = 2
+
+function retrieveLastSegments(path) {
+    if (!path || typeof path !== 'string') {
+        return '';
+    }
+    const segments = path.split('/').filter(segment => segment !== '');
+    if (segments.length <= VERSIONED_SEGMENTS) {
+        console.warn(`Path "${path}" does not have enough segments to extract a page path.`);
+        return '';
+    }
+
+    return segments.slice(VERSIONED_SEGMENTS).join('/');
+}
+
+function replaceLastPathSegment(path, newSegment) {
+    if (!path || typeof path !== 'string') {
+        return path;
+    }
+
+    const segments = path.split('/').filter(segment => segment !== '');
+    if (segments.length <= VERSIONED_SEGMENTS) {
+        console.warn(`Path "${path}" does not have enough segments to extract base path.`);
+        return path;
+    }
+
+    const base = segments.slice(0, VERSIONED_SEGMENTS).join('/');
+    return '/' + base + '/' + newSegment;
+}
+
+
+module.exports = (targetPath, currentPath) => {
+  return replaceLastPathSegment(targetPath, retrieveLastSegments(currentPath));
+};

documentation/src/main/antora/supplemental-ui/partials/header-content.hbs

@@ -1,7 +1,7 @@
 <svg xmlns="http://www.w3.org/2000/svg" focusable="false" style="display: none;">
     <symbol id="talend-logo-square">
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
-            <path fill="#FFF" d="M8,5.32907052e-14 C12.4182648,5.32907052e-14 16,3.58173516 16,8 C16,12.4188737 12.4182648,16.0006088 8,16.0006088 C3.58173516,16.0006088 0,12.4188737 0,8 C0,3.58173516 3.58173516,5.32907052e-14 8,5.32907052e-14 Z M7.86070588,3.63987227 C7.41418487,4.67207395 6.53747899,5.46891429 5.4532437,5.80834286 C5.4532437,5.80834286 5.23179832,5.86098151 5.28867227,6.09271261 C5.29532773,6.11267899 5.30137815,6.13264538 5.31105882,6.15261176 C5.34191597,6.21735126 5.37942857,6.25062857 5.42359664,6.25607395 L6.13391597,6.25607395 L6.13391597,10.6517042 C6.13391597,11.2755025 6.32329412,11.7117378 6.70205042,11.959805 C7.08020168,12.2072672 7.58843697,12.3306958 8.22554622,12.3306958 C8.42521008,12.3306958 8.65633613,12.2937882 8.91952941,12.218763 C9.18272269,12.1431328 9.43078992,12.0469311 9.66312605,11.9295529 C9.89606723,11.8127798 10.0672941,11.6941916 10.1780168,11.5737882 C10.2046387,11.5568471 10.2046387,11.5090487 10.1780168,11.4316034 C10.151395,11.354158 10.1138824,11.282158 10.0648739,11.2162084 C10.0164706,11.1496538 9.97895798,11.1230319 9.95233613,11.1363429 C9.78413445,11.2198387 9.60020168,11.2912336 9.40114286,11.3487126 C9.20208403,11.4061916 9.02904202,11.4352336 8.88322689,11.4352336 C8.7192605,11.4352336 8.59401681,11.397721 8.50810084,11.325721 C8.42157983,11.2525109 8.35986555,11.1169815 8.32235294,10.9203429 C8.28423529,10.7237042 8.26547899,10.4363092 8.26547899,10.0599731 L8.26547899,6.24276303 L9.69337815,6.24276303 C9.74178151,6.24276303 9.78715966,6.19617479 9.82951261,6.10239328 C9.8712605,6.01042689 9.89243697,5.89546891 9.89243697,5.75812437 C9.89243697,5.70004034 9.87791597,5.64861176 9.84887395,5.60504874 C9.82043697,5.56088067 9.78171429,5.53667899 9.73331092,5.5324437 L8.26547899,5.5324437 L8.26547899,3.6792 C8.26547899,3.60235966 8.21465546,3.54790588 8.1245042,3.51099832 C7.95811765,3.45896471 7.86070588,3.63987227 7.86070588,3.63987227 Z"</path>
+            <path fill="#FFF" d="M8,5.32907052e-14 C12.4182648,5.32907052e-14 16,3.58173516 16,8 C16,12.4188737 12.4182648,16.0006088 8,16.0006088 C3.58173516,16.0006088 0,12.4188737 0,8 C0,3.58173516 3.58173516,5.32907052e-14 8,5.32907052e-14 Z M7.86070588,3.63987227 C7.41418487,4.67207395 6.53747899,5.46891429 5.4532437,5.80834286 C5.4532437,5.80834286 5.23179832,5.86098151 5.28867227,6.09271261 C5.29532773,6.11267899 5.30137815,6.13264538 5.31105882,6.15261176 C5.34191597,6.21735126 5.37942857,6.25062857 5.42359664,6.25607395 L6.13391597,6.25607395 L6.13391597,10.6517042 C6.13391597,11.2755025 6.32329412,11.7117378 6.70205042,11.959805 C7.08020168,12.2072672 7.58843697,12.3306958 8.22554622,12.3306958 C8.42521008,12.3306958 8.65633613,12.2937882 8.91952941,12.218763 C9.18272269,12.1431328 9.43078992,12.0469311 9.66312605,11.9295529 C9.89606723,11.8127798 10.0672941,11.6941916 10.1780168,11.5737882 C10.2046387,11.5568471 10.2046387,11.5090487 10.1780168,11.4316034 C10.151395,11.354158 10.1138824,11.282158 10.0648739,11.2162084 C10.0164706,11.1496538 9.97895798,11.1230319 9.95233613,11.1363429 C9.78413445,11.2198387 9.60020168,11.2912336 9.40114286,11.3487126 C9.20208403,11.4061916 9.02904202,11.4352336 8.88322689,11.4352336 C8.7192605,11.4352336 8.59401681,11.397721 8.50810084,11.325721 C8.42157983,11.2525109 8.35986555,11.1169815 8.32235294,10.9203429 C8.28423529,10.7237042 8.26547899,10.4363092 8.26547899,10.0599731 L8.26547899,6.24276303 L9.69337815,6.24276303 C9.74178151,6.24276303 9.78715966,6.19617479 9.82951261,6.10239328 C9.8712605,6.01042689 9.89243697,5.89546891 9.89243697,5.75812437 C9.89243697,5.70004034 9.87791597,5.64861176 9.84887395,5.60504874 C9.82043697,5.56088067 9.78171429,5.53667899 9.73331092,5.5324437 L8.26547899,5.5324437 L8.26547899,3.6792 C8.26547899,3.60235966 8.21465546,3.54790588 8.1245042,3.51099832 C7.95811765,3.45896471 7.86070588,3.63987227 7.86070588,3.63987227 Z"/>
         </svg>
     </symbol>
     <symbol id="talend-component-kit-positive">
@@ -15,7 +15,7 @@
     </symbol>
 </svg>
 
-<header class="{{or ./headerClass 'global-header'}}">
+<header class="{{or headerClass 'global-header'}}">
   <nav class="navbar navbar-default">
       <div class="navbar-text-content nav navbar-nav">
         <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
@@ -46,7 +46,7 @@
                 <li class="navbar-item version
                   {{~#if (and (eq site.components @root.page.component) (eq this @root.page.componentVersion))}} is-current{{/if~}}
                   {{~#if (eq this site.components.latest)}} is-latest{{/if}}">
-                    <a href="{{{relativize ./url @root.page.url}}}">{{./version}}{{~#if (eq this site.components.latest)}} (dev){{/if}}</a>
+                    <a href="{{{relativize (or (validatePath (swapLastSegment this.url @root.page.url)) this.url) @root.page.url}}}">{{this.version}}{{~#if (eq this site.components.latest)}} (dev){{/if}}</a>
                 </li>
               {{/each}}
           </ul>