fix: Updated page titles

typedoc2md · Oct 22, 2023 · 1b00751 · 1b00751
1 parent e7d0ac6
commit 1b00751
Show file tree

Hide file tree

Showing 23 changed files with 2,638 additions and 3,186 deletions.
diff --git a/.changeset/spicy-students-fetch.md b/.changeset/spicy-students-fetch.md
@@ -0,0 +1,6 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Updated default `--indexPageTitle` to {projectName}
+- Renamed `--titleTemplate` -> `--memberPageTemplate`
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -17,17 +17,17 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.26.2",
-    "@types/cross-spawn": "^6.0.3",
-    "@types/fs-extra": "^11.0.2",
+    "@types/cross-spawn": "^6.0.4",
+    "@types/fs-extra": "^11.0.3",
     "@types/glob": "^8.1.0",
-    "@types/jest": "^29.5.5",
-    "@types/node": "^20.8.4",
-    "@typescript-eslint/eslint-plugin": "^6.7.5",
-    "@typescript-eslint/parser": "^6.7.5",
+    "@types/jest": "^29.5.6",
+    "@types/node": "^20.8.7",
+    "@typescript-eslint/eslint-plugin": "^6.8.0",
+    "@typescript-eslint/parser": "^6.8.0",
     "consola": "^3.2.3",
     "copyfiles": "^2.4.1",
     "cross-spawn": "^7.0.3",
-    "eslint": "^8.51.0",
+    "eslint": "^8.52.0",
     "glob": "^10.3.10",
     "jest": "^29.7.0",
     "markdownlint": "^0.31.1",

diff --git a/packages/typedoc-plugin-markdown/README.md b/packages/typedoc-plugin-markdown/README.md
@@ -62,7 +62,7 @@ This plugin exposes additional options. Please see [Options Guide](./docs/guides
 * [`--hideBreadcrumbs`](./docs/guides/options.md#--hidebreadcrumbs)
 * [`--hideInPageTOC`](./docs/guides/options.md#--hideinpagetoc)
 * [`--indexPageTitle`](./docs/guides/options.md#--indexpagetitle)
-* [`--titleTemplate`](./docs/guides/options.md#--titletemplate)
+* [`--memberPageTitle`](./docs/guides/options.md#--memberpagetitle)
 * [`--excludeGroups`](./docs/guides/options.md#--excludegroups)
 * [`--useCodeBlocks`](./docs/guides/options.md#--usecodeblocks)
 * [`--expandObjects`](./docs/guides/options.md#--expandobjects)

diff --git a/packages/typedoc-plugin-markdown/docs/guides/options.md b/packages/typedoc-plugin-markdown/docs/guides/options.md
@@ -12,7 +12,7 @@
   * [`--hideBreadcrumbs`](#--hidebreadcrumbs)
   * [`--hideInPageTOC`](#--hideinpagetoc)
   * [`--indexPageTitle`](#--indexpagetitle)
-  * [`--titleTemplate`](#--titletemplate)
+  * [`--memberPageTitle`](#--memberpagetitle)
   * [`--excludeGroups`](#--excludegroups)
   * [`--useCodeBlocks`](#--usecodeblocks)
   * [`--expandObjects`](#--expandobjects)
@@ -205,25 +205,29 @@ The title of project index page. Defaults to `"{projectName}"`.
 
 #### Usage
 
-This provides a mechanism to change the main project index page title.
+Provides a mechanism to change the main project index page title.
 
-Note this will also serve as the root breadcrumb text.
+Defaults to `{projectName}` - a placeholder that renders the project name and version (when `--includeVersion` is set).
 
 [↑ Top](#options-guide)
 
 ***
 
-### `--titleTemplate`
+### `--memberPageTitle`
 
-Specify a template for displaying page titles. Defaults to `"{kind}: {name}"`.
+The template for displaying page titles of members. Defaults to `"{kind}: {name}"`.
 
 ```shell
---titleTemplate <string>
+--memberPageTitle <string>
 ```
 
 #### Usage
 
-Supports {kind} and {name} placeholders.
+Provides a mechanism to change the page title of members.
+
+Supports `{kind}` and `{name}` placeholders.
+
+e.g "Class: MyClassName"
 
 [↑ Top](#options-guide)
 

diff --git a/packages/typedoc-plugin-markdown/src/plugin/options/config.ts b/packages/typedoc-plugin-markdown/src/plugin/options/config.ts
@@ -164,27 +164,31 @@ export const hideInPageTOC: DeclarationOption = {
 };
 
 /**
- * This provides a mechanism to change the main project index page title.
+ * Provides a mechanism to change the main project index page title.
  *
- * Note this will also serve as the root breadcrumb text.
+ * Defaults to `{projectName}` - a placeholder that renders the project name and version (when `--includeVersion` is set).
  *
  * @category ui
  */
 export const indexPageTitle: DeclarationOption = {
   name: 'indexPageTitle',
   help: 'The title of project index page.',
   type: ParameterType.String,
-  defaultValue: 'API',
+  defaultValue: '{projectName}',
 };
 
 /**
- * Supports {kind} and {name} placeholders.
+ * Provides a mechanism to change the page title of members.
+ *
+ * Supports `{kind}` and `{name}` placeholders.
+ *
+ * e.g "Class: MyClassName"
  *
  * @category ui
  */
-export const titleTemplate: DeclarationOption = {
-  name: 'titleTemplate',
-  help: 'Specify a template for displaying page titles.',
+export const memberPageTitle: DeclarationOption = {
+  name: 'memberPageTitle',
+  help: 'The page title of members.',
   type: ParameterType.String,
   defaultValue: '{kind}: {name}',
 };

diff --git a/packages/typedoc-plugin-markdown/src/plugin/options/models.ts b/packages/typedoc-plugin-markdown/src/plugin/options/models.ts
@@ -10,7 +10,7 @@ declare module 'typedoc' {
     hideBreadcrumbs: boolean;
     hideInPageTOC: boolean;
     indexPageTitle: string;
-    titleTemplate: string;
+    memberPageTitle: string;
     excludeGroups: boolean;
     useCodeBlocks: boolean;
     expandObjects: boolean;
@@ -34,7 +34,7 @@ export interface PluginOptions {
   hideBreadcrumbs: boolean;
   hideInPageTOC: boolean;
   indexPageTitle: string;
-  titleTemplate: string;
+  memberPageTitle: string;
   excludeGroups: boolean;
   useCodeBlocks: boolean;
   expandObjects: boolean;

diff --git a/packages/typedoc-plugin-markdown/src/theme/navigation-context.ts b/packages/typedoc-plugin-markdown/src/theme/navigation-context.ts
@@ -22,7 +22,7 @@ export class NavigationContext {
 
     if (hasReadme) {
       this.navigation.push({
-        title: 'README',
+        title: 'Readme',
         url: entryFileName,
       });
       this.navigation.push({

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/breadcrumbs.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/breadcrumbs.ts
@@ -21,12 +21,7 @@ export function breadcrumbs(
     return '';
   }
 
-  md.push(
-    link(
-      context.options.getValue('indexPageTitle'),
-      context.relativeURL(page.project.url),
-    ),
-  );
+  md.push(link('API', context.relativeURL(page.project.url)));
 
   const breadcrumb = (model: any) => {
     if (model?.parent?.parent) {

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/header.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/header.ts
@@ -49,12 +49,12 @@ function projectHeader(
   }
 
   if (hasReadme) {
-    md.push(link('README', context.relativeURL(entryFileName)));
+    md.push(link('Readme', context.relativeURL(entryFileName)));
   }
   if (hasReadme || !hasBreadcrumbs) {
     md.push(
       link(
-        context.options.getValue('indexPageTitle'),
+        'API',
         hasReadme
           ? context.relativeURL(indexFileName)
           : context.relativeURL(entryFileName),
@@ -86,7 +86,7 @@ function packageHeader(
   if (hasReadme) {
     md.push(
       link(
-        'README',
+        'Readme',
         context.relativeURL(`${packageItem.name}/${entryFileName}`),
       ),
     );

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.title.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/page.title.ts
@@ -5,7 +5,7 @@ import {
 } from 'typedoc';
 import { MarkdownThemeRenderContext } from '../..';
 import { MarkdownPageEvent } from '../../../plugin/events';
-import { getMemberTitle } from '../../helpers';
+import { getMemberTitle, getProjectDisplayName } from '../../helpers';
 
 /**
  * @category Partials
@@ -14,13 +14,20 @@ export function pageTitle(
   context: MarkdownThemeRenderContext,
   page: MarkdownPageEvent<DeclarationReflection | ProjectReflection>,
 ): string {
-  const titleTemplate = context.options.getValue('titleTemplate') as string;
+  const memberPageTitle = context.options.getValue('memberPageTitle') as string;
   const name = getMemberTitle(page.model as DeclarationReflection);
+  const projectName = getProjectDisplayName(
+    page.project,
+    context.options.getValue('includeVersion'),
+  );
+
   if (page.model?.url === page.project.url) {
-    return context.options.getValue('indexPageTitle');
+    return context.options
+      .getValue('indexPageTitle')
+      .replace('{projectName}', projectName);
   }
 
-  return titleTemplate
+  return memberPageTitle
     .replace('{name}', name)
     .replace('{kind}', ReflectionKind.singularString(page.model.kind));
 }
diff --git a/packages/typedoc-plugin-markdown/test/__scripts__/lint.mdx.mjs b/packages/typedoc-plugin-markdown/test/__scripts__/lint.mdx.mjs
@@ -20,7 +20,7 @@ async function lintMdx() {
       await remark().use(remarkMdx).processSync(vfile);
     } catch (e) {
       error = true;
-      consola.error('Error linting MDX');
+      consola.error(`Error linting MDX on file ${file}`);
       throw new Error(e);
     }
   });

diff --git a/packages/typedoc-plugin-markdown/test/__utils__/config.ts b/packages/typedoc-plugin-markdown/test/__utils__/config.ts
@@ -37,7 +37,7 @@ export const FIXTURES: Fixture[] = [
         enumMembersFormat: 'table',
         useCodeBlocks: true,
         expandObjects: true,
-        titleTemplate: '{name}',
+        memberPageTitle: '{name}',
       },
     ],
   },

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap
@@ -1,7 +1,7 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Comments should compile comments for module: (Output File Strategy "members") (Option Group "1") 1`] = `
-"# API
+"# typedoc-stubs
 
 Comments form module comments
 
@@ -64,7 +64,7 @@ Some <p> html </p> inside codeblock
 `;
 
 exports[`Comments should compile comments for module: (Output File Strategy "members") (Option Group "2") 1`] = `
-"# API
+"# typedoc-stubs
 
 Comments form module comments
 
@@ -133,7 +133,7 @@ Some <p> html </p> inside codeblock
 `;
 
 exports[`Comments should compile comments for module: (Output File Strategy "modules") (Option Group "1") 1`] = `
-"# API
+"# typedoc-stubs
 
 Comments form module comments
 
@@ -247,7 +247,7 @@ Some <p> html </p> inside codeblock
 `;
 
 exports[`Comments should compile comments for module: (Output File Strategy "modules") (Option Group "2") 1`] = `
-"# API
+"# typedoc-stubs
 
 Comments form module comments