fix: Tweak breadcrumbs output

typedoc2md · May 1, 2023 · 1856797 · 1856797
1 parent 08cfaca
commit 1856797
Show file tree

Hide file tree

Showing 10 changed files with 55 additions and 51 deletions.
diff --git a/.changeset/shaggy-pens-end.md b/.changeset/shaggy-pens-end.md
@@ -3,4 +3,4 @@
 ---
 
 - Added `--TOCFormat` option
-- Added `--longPageTitles` option
+- Tweak breadcrumbs output
diff --git a/packages/docusaurus-plugin-typedoc/src/options.ts b/packages/docusaurus-plugin-typedoc/src/options.ts
@@ -1,5 +1,4 @@
 import { PluginOptions } from './models';
-const plugin = require.resolve('docusaurus-plugin-typedoc');
 
 const DEFAULT_PLUGIN_OPTIONS: Partial<PluginOptions> = {
   id: 'default',
@@ -17,7 +16,6 @@ const DEFAULT_PLUGIN_OPTIONS: Partial<PluginOptions> = {
   watch: false,
   enableFrontmatter: true,
   numberPrefixOutput: true,
-  plugin: [plugin],
 };
 
 export const getPluginOptions = (
@@ -30,7 +28,6 @@ export const getPluginOptions = (
       ...DEFAULT_PLUGIN_OPTIONS.sidebar,
       ...opts.sidebar,
     },
-    plugin: [DEFAULT_PLUGIN_OPTIONS.plugin, ...(opts.plugin || [])],
   };
   return options as PluginOptions;
 };
diff --git a/packages/docusaurus-plugin-typedoc/src/plugin.docusaurus.ts b/packages/docusaurus-plugin-typedoc/src/plugin.docusaurus.ts
@@ -8,6 +8,7 @@ import {
 import { load as loadTypedocPluginMarkdown } from 'typedoc-plugin-markdown';
 import { PluginOptions } from './models';
 import { getPluginOptions } from './options';
+import { load as loadDocusaurusTypedocPlugin } from './plugin.typedoc';
 
 // store list of plugin ids when running multiple instances
 const apps: string[] = [];
@@ -60,6 +61,7 @@ async function generateTypedoc(context: any, opts: Partial<PluginOptions>) {
   app.options.addReader(new TSConfigReader());
 
   loadTypedocPluginMarkdown(app);
+  loadDocusaurusTypedocPlugin(app);
 
   await app.bootstrapWithPlugins(
     optionsPassedToTypeDoc as unknown as Partial<TypeDocOptions>,

diff --git a/packages/typedoc-plugin-markdown/package.json b/packages/typedoc-plugin-markdown/package.json
@@ -16,8 +16,8 @@
     "test": "jest --colors --updateSnapshot",
     "build-and-test": "npm run build && npm run test",
     "docs": "npm run build && npm-run-all docs:*",
-    "docs:md-1": "typedoc --plugin typedoc-plugin-markdown --plugin typedoc-plugin-mdn-links --options ../../stubs/typedoc.json --longPageTitles --enableFrontmatter --TOCFormat \"table\"  --out ./out/md/md-1",
-    "docs:md-2": "typedoc --plugin typedoc-plugin-markdown --options ../../stubs/typedoc.json --indexPageTitle \"Overview\"  --indentifiersAsCodeBlocks --groupByKinds --propertiesFormat \"table\" --enumMembersFormat \"table\" --readme \"none\" --kindsWithOwnFile \"none\"  --out ./out/md/md-2",
+    "docs:md-1": "typedoc --plugin typedoc-plugin-markdown --plugin typedoc-plugin-mdn-links --plugin ../../stubs/custom-plugin --options ../../stubs/typedoc.json --longPageTitles --enableFrontmatter --TOCFormat \"table\"  --out ./out/md/md-1",
+    "docs:md-2": "typedoc --plugin typedoc-plugin-markdown --options ../../stubs/typedoc.json --enableFrontmatter --indexPageTitle \"Overview\"  --indentifiersAsCodeBlocks --groupByKinds --propertiesFormat \"table\" --enumMembersFormat \"table\" --readme \"none\" --kindsWithOwnFile \"none\"  --out ./out/md/md-2",
     "docs:html": "typedoc --options ../../stubs/typedoc.json --out ./out/html"
   },
   "author": "Thomas Grey",

diff --git a/packages/typedoc-plugin-markdown/src/partials/breadcrumbs.ts b/packages/typedoc-plugin-markdown/src/partials/breadcrumbs.ts
@@ -8,42 +8,36 @@ export function breadcrumbs(
   context: MarkdownThemeRenderContext,
   page: PageEvent<ProjectReflection | DeclarationReflection>,
 ) {
-  if (page.model) {
-    if (page.model.kind) {
-      const md: string[] = [];
-      const projectName = getProjectDisplayName(
-        page.project,
-        context.getOption('includeVersion'),
-      );
+  const md: string[] = [];
+  const projectName = getProjectDisplayName(
+    page.project,
+    context.getOption('includeVersion'),
+  );
+
+  const entryDocument = context.getOption('entryDocument');
+
+  if (page.url === page.project.url || page.url === entryDocument) {
+    return '';
+  }
+
+  md.push(link(projectName, context.relativeURL(page.project.url)));
+  if (
+    page.model?.parent?.parent &&
+    (page.url !== page.project.url || page.url !== entryDocument)
+  ) {
+    if (page?.model?.parent?.parent?.parent) {
       md.push(
-        page.url === page.project.url
-          ? projectName
-          : link(
-              projectName,
-              context.relativeURL(
-                context.getOption('readme').endsWith('none')
-                  ? context.getOption('entryDocument')
-                  : page.project.url,
-              ),
-            ),
+        `[${escapeChars(page.model.parent.parent.name)}](${context.relativeURL(
+          page.model?.parent?.parent.url,
+        )})`,
       );
-      if (page.model.parent && page.model.parent.parent) {
-        if (page?.model?.parent?.parent.parent) {
-          md.push(
-            `[${escapeChars(
-              page.model.parent.parent.name,
-            )}](${context.relativeURL(page.model?.parent?.parent.url)})`,
-          );
-        }
-        md.push(
-          `[${page.model.parent.name}](${context.relativeURL(
-            page.model.parent.url,
-          )})`,
-        );
-      }
-      md.push(escapeChars(page.model.name));
-      return md.length > 1 ? `${md.join(' / ')}` : '';
     }
+    md.push(
+      `[${page.model.parent.name}](${context.relativeURL(
+        page.model.parent.url,
+      )})`,
+    );
   }
-  return '';
+  md.push(escapeChars(page.model.name));
+  return md.length > 1 ? `${md.join(' > ')}` : '';
 }
diff --git a/packages/typedoc-plugin-markdown/src/partials/toc.ts b/packages/typedoc-plugin-markdown/src/partials/toc.ts
@@ -31,7 +31,7 @@ export function toc(
     );
     const subHeadingLevel = headingLevel + 1;
 
-    md.push(heading(headingLevel, 'Table of Contents') + '\n\n');
+    md.push(heading(headingLevel, 'Index') + '\n\n');
 
     if (reflection.categories?.length) {
       reflection.categories.forEach((item) => {

diff --git a/packages/typedoc-plugin-markdown/src/support/helpers.ts b/packages/typedoc-plugin-markdown/src/support/helpers.ts
@@ -58,11 +58,8 @@ export function getReflectionHeadingLevel(
 export function getReflectionTitle(
   reflection: DeclarationReflection,
   typeParams = false,
-  longTitle = false,
 ) {
-  const md = [
-    escapeChars(longTitle ? reflection.getFriendlyFullName() : reflection.name),
-  ];
+  const md = [escapeChars(reflection.name)];
   if (reflection.signatures?.length) {
     md.push('()');
   }

diff --git a/packages/typedoc-plugin-markdown/src/templates/project.ts b/packages/typedoc-plugin-markdown/src/templates/project.ts
@@ -12,6 +12,10 @@ export function projectTemplate(
     md.push(context.partials.frontmatter(page));
   }
 
+  if (!context.getOption('hideBreadcrumbs')) {
+    md.push(context.partials.breadcrumbs(page));
+  }
+
   if (!context.getOption('hidePageTitle')) {
     md.push(heading(1, context.partials.pageTitle(page)));
   }

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/breadcrumbs.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/breadcrumbs.spec.ts.snap
@@ -1,13 +1,13 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`Breadcrumbs: (with readme) should compile README breadcrumbs' 1`] = `"[typedoc-plugin-markdown](modules.md) / typedoc-plugin-markdown"`;
+exports[`Breadcrumbs: (with readme) should compile README breadcrumbs' 1`] = `"**typedoc-plugin-markdown**"`;
 
-exports[`Breadcrumbs: (with readme) should compile class breadcrumbs' 1`] = `"[typedoc-plugin-markdown](modules.md) / Breadcrumbs"`;
+exports[`Breadcrumbs: (with readme) should compile class breadcrumbs' 1`] = `"[typedoc-plugin-markdown](modules.md) > Breadcrumbs"`;
 
-exports[`Breadcrumbs: (with readme) should compile entryPoint (globals) breadcrumbs' 1`] = `"[typedoc-plugin-markdown](modules.md) / typedoc-plugin-markdown"`;
+exports[`Breadcrumbs: (with readme) should compile entryPoint (globals) breadcrumbs' 1`] = `"[typedoc-plugin-markdown](modules.md) > typedoc-plugin-markdown"`;
 
-exports[`Breadcrumbs: (with readme) should compile module breadcrumbs' 1`] = `"[typedoc-plugin-markdown](modules.md) / Breadcrumbs"`;
+exports[`Breadcrumbs: (with readme) should compile module breadcrumbs' 1`] = `"[typedoc-plugin-markdown](modules.md) > Breadcrumbs"`;
 
-exports[`Breadcrumbs: (without readme) should compile class breadcrumbs' 1`] = `"[typedoc-plugin-markdown](README.md) / Breadcrumbs"`;
+exports[`Breadcrumbs: (without readme) should compile class breadcrumbs' 1`] = `"[typedoc-plugin-markdown](README.md) > Breadcrumbs"`;
 
-exports[`Breadcrumbs: (without readme) should compile module breadcrumbs' 1`] = `"[typedoc-plugin-markdown](README.md) / Breadcrumbs"`;
+exports[`Breadcrumbs: (without readme) should compile module breadcrumbs' 1`] = `"[typedoc-plugin-markdown](README.md) > Breadcrumbs"`;
diff --git a/stubs/custom-plugin.js b/stubs/custom-plugin.js
@@ -0,0 +1,10 @@
+const { PageEvent } = require('typedoc');
+const {
+  FrontmatterEvent,
+} = require('../packages/typedoc-plugin-markdown/dist');
+
+module.exports = {
+  load(app) {
+    app.renderer.on(PageEvent.BEGIN, (page) => {});
+  },
+};