feat: allow external links on main level

kiwigrid · Dec 19, 2024 · 97a399b · 97a399b
1 parent 0103210
commit 97a399b
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 37 deletions.
diff --git a/README.md b/README.md
@@ -72,7 +72,7 @@ antora:
 
 The definition and the dedicated component resource are following the same schema:
 
-A menu definition consists a list if of menu groups.
+A menu definition consists of a list if of menu groups, component references and/or external links.
 
 A **group** is defined as:
 
@@ -182,7 +182,7 @@ The templates are supporting the following parameter:
   * Resolvable (either absolute or relative to playbook base) document URI.
   * The parameter contains `#`, if the parameter `resolved` is marked `false`.
 * `component`
-  * the components name (from antory.yml), if resolved, or `null` for unresolved module references.
+  * the components name (from antory.yml), if resolved, or `null` for unresolved module references and external links.
 
 ### Sample
 
@@ -208,8 +208,8 @@ The template `main-menu` is created by the extension as:
 ```handlebars
 {{> main-menu-group-start level=0 group_title="Products"}}
     {{> main-menu-group-start level=1 group_title="sub group"}}
-        {{> main-menu-docref resolved=true external=false ref="/existing-module/latest/<startpage of existing-module>.html" doc_title="<Title of existing-module>"}}
-        {{> main-menu-docref resolved=false external=false ref="#" doc_title="not-existing-module"}}
+        {{> main-menu-docref resolved=true external=false ref="/existing-module/latest/<startpage of existing-module>.html" doc_title="<Title of existing-module>" component="<name of existing-module>"}}
+        {{> main-menu-docref resolved=false external=false ref="#" doc_title="not-existing-module" component="null"}}
         {{> main-menu-docref resolved=true external=true ref="https://docs.antora.org" doc_title="Antora Doc"}}
     {{> main-menu-group-end}}
 {{> main-menu-group-end}}

diff --git a/extensions/v1/builder.js b/extensions/v1/builder.js
@@ -62,46 +62,40 @@ class MenuBuilder {
     build(contentCatalog) {
         // resolved menu template
         const mainMenuContent = new MenuContent(this.hbs.groupStart, this.hbs.groupEnd, this.hbs.docRef);
-        this.menu.forEach(entry => {
-            if (entry.title) {
-                mainMenuContent.add(this.inspectGroupEntry(undefined, entry, contentCatalog));
-            } else if (entry.module) {
-                const component = contentCatalog.getComponent(entry.module);
-                mainMenuContent.add(component
-                    ? Document.resolved(component.latest.title, component.latest.url, component.name)
-                    : Document.unresolved(entry.module));
-            } else {
-                throw new Error(`root element must have a title and optional entries ${this.toString(entry)}`);
-            }
-        })
+        this.menu.forEach(entry => { mainMenuContent.add(this.inspectEntry(entry, contentCatalog)) })
         return mainMenuContent.toPartialHandlebar();
     }
 
     toString(entry) {
-        let s = `${entry.toString()} {`;
-        Object.getOwnPropertyNames(entry).forEach(key => {
-            s += `${key}=${entry[key]}, `
-        });
-        return `${s} }`;
+        const values = Object.getOwnPropertyNames(entry)
+            .map((key) => `${key}=${entry[key]}`)
+            .join(",");
+        return `${entry.toString()} { ${values} }`;
     }
 
-    inspectGroupEntry(parentNode, entry, contentCatalog) {
-        const groupNode = new Group(entry.title);
-        parentNode?.add(groupNode);
-        entry.entries?.forEach((subEntry) => {
-            if (subEntry.module) {
-                const component = contentCatalog.getComponent(subEntry.module);
-                groupNode.add(component
-                    ? Document.resolved(component.latest.title, component.latest.url, component.name)
-                    : Document.unresolved(entry.module));
-            } else if (subEntry.link) {
-                groupNode.add(Document.external(subEntry.title, subEntry.link));
-            } else if (subEntry.title) {
-                this.inspectGroupEntry(groupNode, subEntry, contentCatalog);
-            }
-        })
-        return groupNode;
+    inspectEntry(entry, contentCatalog) {
+        if(entry.link) {
+            // external link
+            return Document.external(entry.title, entry.link);
+        } else if(entry.module) {
+            // module reference
+            const component = contentCatalog.getComponent(entry.module);
+            return component
+                ? Document.resolved(component.latest.title, component.latest.url, component.name)
+                : Document.unresolved(entry.module);
+        } else if(entry.title) {
+            // group
+            const groupNode = new Group(entry.title);
+            entry.entries?.forEach((subEntry) => {
+                groupNode.add(this.inspectEntry(subEntry, contentCatalog));
+            });
+            return groupNode;
+        } else {
+            // unspecified
+            throw new Error(`bad entry format. Couldn't identify one of [group, module reference or external link]. Entry: ${this.toString(entry)}`)
+        }
     }
+
 }