fix: Updates to respect TypeDocs additional navigation options.

typedoc2md · Apr 20, 2024 · 60234c7 · 60234c7
1 parent a5c672d
commit 60234c7
Show file tree

Hide file tree

Showing 10 changed files with 205 additions and 117 deletions.
diff --git a/.changeset/nice-goats-dress.md b/.changeset/nice-goats-dress.md
@@ -0,0 +1,5 @@
+---
+"typedoc-plugin-markdown": patch
+---
+
+- Updates to respect TypeDocs `navigationLinks`, `sidebarLinks` and `navigationLeaves` options.
diff --git a/devtools/packages/fixtures/cli.ts b/devtools/packages/fixtures/cli.ts
@@ -154,6 +154,7 @@ function objectToOptions(obj: any) {
           }, []),
         ];
       }
+
       if (typeof curr[1] === 'object') {
         return [
           ...prev,

diff --git a/packages/typedoc-plugin-markdown/src/theme/core/navigation-builder.ts b/packages/typedoc-plugin-markdown/src/theme/core/navigation-builder.ts
@@ -17,8 +17,20 @@ export function buildNavigation(
 ) {
   const options = theme.application.options;
   const navigationOptions = options.getValue('navigation');
+  const sidebarLinks = options.getValue('sidebarLinks');
+  const navigationLeaves = options.getValue('navigationLeaves');
 
   const navigation: NavigationItem[] = [];
+
+  if (sidebarLinks) {
+    Object.entries(sidebarLinks).forEach(([title, path]) => {
+      navigation.push({
+        title,
+        path,
+      });
+    });
+  }
+
   const packagesMeta = (theme.application.renderer as MarkdownRenderer)
     .packagesMeta;
 
@@ -217,6 +229,13 @@ export function buildNavigation(
     reflection: DeclarationReflection,
     outputFileStrategy?: OutputFileStrategy,
   ): NavigationItem[] | null {
+    const noChildren =
+      [ReflectionKind.Module, ReflectionKind.Namespace].includes(
+        reflection.kind,
+      ) && navigationLeaves.includes(reflection.getFullName());
+    if (noChildren) {
+      return null;
+    }
     if (
       reflection.groups?.some((group) => group.allChildrenHaveOwnDocument())
     ) {

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.header.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.header.ts
@@ -27,6 +27,7 @@ export function header(this: MarkdownThemeContext): string {
 
   const getProjectHeader = () => {
     const fileExtension = this.options.getValue('fileExtension');
+    const navigationLinksOptions = this.options.getValue('navigationLinks');
     const entryFileName = `${path.parse(this.options.getValue('entryFileName')).name}${fileExtension}`;
     const titleLink = this.options.getValue('titleLink');
 
@@ -95,6 +96,16 @@ export function header(this: MarkdownThemeContext): string {
       }
     }
 
+    const extraLinks: string[] = [];
+    const navigationLinks = Object.entries(navigationLinksOptions);
+    if (navigationLinks?.length) {
+      md.push('•');
+      navigationLinks.forEach(([key, value]) => {
+        extraLinks.push(link(key, value));
+      });
+      md.push(extraLinks.join(' \\| '));
+    }
+
     return `${md.join(' ')}\n\n***\n`;
   };
 

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts
@@ -106,9 +106,10 @@ const config: Record<string, Fixture> = {
         indexPageTitle: '{projectName}',
         categorizeByGroup: false,
         navigation: {
-          includeGroups: false,
+          includeGroups: true,
           includeCategories: true,
         },
+        options: './test/fixtures/typedoc.nav-options.cjs',
       },
     ],
   },
@@ -217,8 +218,8 @@ const config: Record<string, Fixture> = {
     options: [
       {
         includeVersion: true,
-        titleLink: 'http://www.google.com',
-        options: './test/fixtures/typedoc.text.cjs',
+        titleLink: 'http://www.example.com',
+        options: './test/fixtures/typedoc.text-options.cjs',
         propertiesFormat: 'table',
         navigation: {
           includeGroups: true,

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/typedoc.nav-options.cjs b/packages/typedoc-plugin-markdown/test/fixtures/typedoc.nav-options.cjs
@@ -0,0 +1,13 @@
+const baseOptions = require('../../../../devtools/packages/fixtures/typedoc.cjs');
+module.exports = {
+  ...baseOptions,
+  navigationLinks: {
+    'Nav Link 1': 'http://example.com',
+    'Nav Link 2': 'http://example.com',
+  },
+  navigationLeaves: ['basic', 'has-references'],
+  sidebarLinks: {
+    'Sidebar Example 1': 'http://example.com',
+    'Sidebar Example 2': 'http://example.com',
+  },
+};
diff --git a/...n-markdown/test/fixtures/typedoc.text.cjs → ...wn/test/fixtures/typedoc.text-options.cjs b/...n-markdown/test/fixtures/typedoc.text.cjs → ...wn/test/fixtures/typedoc.text-options.cjs
@@ -1,4 +1,3 @@
-const path = require('path');
 const baseOptions = require('../../../../devtools/packages/fixtures/typedoc.cjs');
 module.exports = {
   ...baseOptions,

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap
@@ -36,7 +36,7 @@ A basic module
 `;
 
 exports[`Groups should compile basic module index page: (Output File Strategy "members") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](../index.md)
+"**typedoc-stubs** • [API](../index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -153,7 +153,7 @@ A basic module
 `;
 
 exports[`Groups should compile basic module index page: (Output File Strategy "modules") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](index.md)
+"**typedoc-stubs** • [API](index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -311,7 +311,7 @@ A module that contains categories
 `;
 
 exports[`Groups should compile categories group page: (Output File Strategy "modules") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](index.md)
+"**typedoc-stubs** • [API](index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -431,7 +431,7 @@ A module that contains categories
 `;
 
 exports[`Groups should compile categories index page: (Output File Strategy "members") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](../index.md)
+"**typedoc-stubs** • [API](../index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -499,7 +499,7 @@ A module that contains custom groupings
 `;
 
 exports[`Groups should compile custom groups index page: (Output File Strategy "members") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](../index.md)
+"**typedoc-stubs** • [API](../index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -565,7 +565,7 @@ exports[`Groups should compile index page for project: (Output File Strategy "me
 `;
 
 exports[`Groups should compile index page for project: (Output File Strategy "members") (Option Group "2") 1`] = `
-"**typedoc-stubs** • API
+"**typedoc-stubs** • API • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -607,7 +607,7 @@ exports[`Groups should compile index page for project: (Output File Strategy "mo
 `;
 
 exports[`Groups should compile index page for project: (Output File Strategy "modules") (Option Group "2") 1`] = `
-"**typedoc-stubs** • API
+"**typedoc-stubs** • API • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -649,7 +649,7 @@ exports[`Groups should compile module index for a namespace: (Output File Strate
 `;
 
 exports[`Groups should compile module index for a namespace: (Output File Strategy "members") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](../../../index.md)
+"**typedoc-stubs** • [API](../../../index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -688,7 +688,7 @@ exports[`Groups should compile module index for a namespace: (Output File Strate
 `;
 
 exports[`Groups should compile module index for a namespace: (Output File Strategy "modules") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](../../../index.md)
+"**typedoc-stubs** • [API](../../../index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -759,7 +759,7 @@ A module that contains namespaces
 `;
 
 exports[`Groups should compile module index with namespaces index page: (Output File Strategy "members") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](../index.md)
+"**typedoc-stubs** • [API](../index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -947,7 +947,7 @@ A module that contains namespaces
 `;
 
 exports[`Groups should compile module index with namespaces index page: (Output File Strategy "modules") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](../index.md)
+"**typedoc-stubs** • [API](../index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -1135,7 +1135,7 @@ Renames and re-exports [defaultFunction](has-references.md#defaultfunction)
 `;
 
 exports[`Groups should compile references group page: (Output File Strategy "modules") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](index.md)
+"**typedoc-stubs** • [API](index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***
 
@@ -1213,7 +1213,7 @@ Renames and re-exports [defaultFunction](functions/defaultFunction.md)
 `;
 
 exports[`Groups should compile references index page: (Output File Strategy "members") (Option Group "2") 1`] = `
-"**typedoc-stubs** • [API](../index.md)
+"**typedoc-stubs** • [API](../index.md) • [Nav Link 1](http://example.com) \\| [Nav Link 2](http://example.com)
 
 ***