feat: Exposed mergeReadme option

typedoc2md · Nov 30, 2023 · 1eef173 · 1eef173
1 parent 206e4af
commit 1eef173
Show file tree

Hide file tree

Showing 14 changed files with 213 additions and 33 deletions.
diff --git a/.changeset/mean-fishes-buy.md b/.changeset/mean-fishes-buy.md
@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Expose `mergeReadme` option
diff --git a/packages/typedoc-plugin-markdown/README.md b/packages/typedoc-plugin-markdown/README.md
@@ -59,6 +59,7 @@ Options that configure how files are generated.
 * [`--membersWithOwnFile`](./docs/plugin-options.md#--memberswithownfile)
 * [`--entryFileName`](./docs/plugin-options.md#--entryfilename)
 * [`--entryModule`](./docs/plugin-options.md#--entrymodule)
+* [`--mergeReadme`](./docs/plugin-options.md#--mergereadme)
 
 #### Structure and formatting options
 

diff --git a/packages/typedoc-plugin-markdown/docs/plugin-options.md b/packages/typedoc-plugin-markdown/docs/plugin-options.md
@@ -9,6 +9,7 @@ This document describes all the additional options exposed by the plugin.
   * [`--membersWithOwnFile`](#--memberswithownfile)
   * [`--entryFileName`](#--entryfilename)
   * [`--entryModule`](#--entrymodule)
+  * [`--mergeReadme`](#--mergereadme)
 * [Structure and formatting options](#structure-and-formatting-options)
   * [`--hidePageHeader`](#--hidepageheader)
   * [`--hidePageTitle`](#--hidepagetitle)
@@ -128,6 +129,25 @@ This is only applicable when multiple modules are resolved.
 
 ***
 
+### `--mergeReadme`
+
+Merges the resolved readme into the project index page. Defaults to `false`.
+
+```shell
+--mergeReadme <boolean>
+```
+
+#### Usage
+
+By default when a readme file is resolved, a seperate Readme page is created. This option prepends the readme contents into the index page.
+
+* This option has no effect when `readme` is set to `none`.
+* When set to `true`, `--indexPageTitle` is ignored.
+
+[↑ Top](#options-guide)
+
+***
+
 ## Structure and formatting options
 
 Options that alter the format and structure of pages.

diff --git a/packages/typedoc-plugin-markdown/src/plugin/options/config.ts b/packages/typedoc-plugin-markdown/src/plugin/options/config.ts
@@ -95,6 +95,20 @@ export const entryModule: DeclarationOption = {
   type: ParameterType.String,
 };
 
+/**
+ * By default when a readme file is resolved, a seperate readme page is created. This option prepends the readme contents into the index page.
+ * This option has no effect when `readme` is set to `none`.
+ *
+ * @category fileOutput
+ *
+ */
+export const mergeReadme: DeclarationOption = {
+  name: 'mergeReadme',
+  help: 'Merges the resolved readme into the project index page.',
+  type: ParameterType.Boolean,
+  defaultValue: false,
+};
+
 /**
  * @category ui
  */

diff --git a/packages/typedoc-plugin-markdown/src/plugin/options/models.ts b/packages/typedoc-plugin-markdown/src/plugin/options/models.ts
@@ -6,6 +6,7 @@ declare module 'typedoc' {
     membersWithOwnFile: any[];
     entryFileName: string;
     entryModule: string;
+    mergeReadme: boolean;
     hidePageHeader: boolean;
     hidePageTitle: boolean;
     hideBreadcrumbs: boolean;
@@ -32,6 +33,7 @@ export interface PluginOptions {
   membersWithOwnFile: any[];
   entryFileName: string;
   entryModule: string;
+  mergeReadme: boolean;
   hidePageHeader: boolean;
   hidePageTitle: boolean;
   hideBreadcrumbs: boolean;

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/partials/header.ts b/packages/typedoc-plugin-markdown/src/theme/resources/partials/header.ts
@@ -52,20 +52,24 @@ function projectHeader(
 
   md.push('•');
 
+  const preserveReadme =
+    Boolean(page.project.readme) && !context.options.getValue('mergeReadme');
+
   const isSinglePage =
     page.project?.groups &&
     page.project?.groups.every((group) => !group.allChildrenHaveOwnDocument());
 
-  if (hasReadme(page.project)) {
+  const preserveModulesPage =
+    (page.project?.groups &&
+      Boolean(
+        page.project?.groups[0]?.children.find(
+          (child) => child.name === context.options.getValue('entryModule'),
+        ),
+      )) ||
+    false;
+
+  if (preserveReadme) {
     const links: string[] = [];
-    const preserveModulesPage =
-      (page.project?.groups &&
-        Boolean(
-          page.project?.groups[0]?.children.find(
-            (child) => child.name === context.options.getValue('entryModule'),
-          ),
-        )) ||
-      false;
 
     links.push(
       link(
@@ -81,7 +85,12 @@ function projectHeader(
     md.push(
       isSinglePage
         ? documentationLabel
-        : link(documentationLabel, context.relativeURL(page.project.url)),
+        : link(
+            documentationLabel,
+            preserveModulesPage
+              ? context.relativeURL(page.project.url)
+              : context.relativeURL(entryFileName),
+          ),
     );
   }
 

diff --git a/packages/typedoc-plugin-markdown/src/theme/resources/templates/project.ts b/packages/typedoc-plugin-markdown/src/theme/resources/templates/project.ts
@@ -16,17 +16,26 @@ export function projectTemplate(
     md.push(context.header(page));
   }
 
+  const includeReadme =
+    context.options.getValue('mergeReadme') && page.model.readme;
+
+  const headingLevel = includeReadme ? 2 : 1;
+
+  if (includeReadme && page.model.readme) {
+    md.push(context.commentParts(page.model.readme));
+  }
+
   if (!context.options.getValue('hidePageTitle')) {
-    md.push(heading(1, context.pageTitle(page)));
+    md.push(heading(headingLevel, context.pageTitle(page)));
   }
 
   if (page.model.comment) {
-    md.push(context.comment(page.model.comment, 2));
+    md.push(context.comment(page.model.comment, headingLevel + 1));
   }
 
-  md.push(context.pageIndex(page, 2));
+  md.push(context.pageIndex(page, headingLevel + 1));
 
-  md.push(context.members(page.model, 2));
+  md.push(context.members(page.model, headingLevel + 1));
 
   md.push(context.footer());
 

diff --git a/packages/typedoc-plugin-markdown/src/theme/urls-context.ts b/packages/typedoc-plugin-markdown/src/theme/urls-context.ts
@@ -17,33 +17,32 @@ import { MarkdownTheme } from './theme';
 export class UrlsContext {
   urls: UrlMapping[] = [];
   anchors: Record<string, string[]> = {};
-  hasReadme: boolean;
-  preserveModulesPage: boolean;
 
   constructor(
     public theme: MarkdownTheme,
     public project: ProjectReflection,
     public options: Partial<TypeDocOptions>,
-  ) {
-    this.hasReadme = Boolean(this.project.readme);
+  ) {}
+
+  /**
+   * Map the models of the given project to the desired output files.
+   * Based on TypeDoc DefaultTheme.getUrls()
+   *
+   * @param project  The project whose urls should be generated.
+   */
+  getUrls(): UrlMapping[] {
+    const preserveReadme =
+      Boolean(this.project.readme) && !this.options.mergeReadme;
 
-    this.preserveModulesPage =
+    const preserveModulesPage =
       (this.project?.groups &&
         Boolean(
           this.project?.groups[0]?.children.find(
             (child) => child.name === this.options.entryModule,
           ),
         )) ||
       false;
-  }
 
-  /**
-   * Map the models of the given project to the desired output files.
-   * Based on TypeDoc DefaultTheme.getUrls()
-   *
-   * @param project  The project whose urls should be generated.
-   */
-  getUrls(): UrlMapping[] {
     const isPackages =
       this.options.entryPointStrategy === EntryPointStrategy.Packages;
 
@@ -53,14 +52,14 @@ export class UrlsContext {
 
     this.project.url = Boolean(this.project.readme)
       ? indexFilename
-      : this.preserveModulesPage
-      ? indexFilename
-      : this.options.entryFileName;
+      : preserveModulesPage
+        ? indexFilename
+        : this.options.entryFileName;
 
-    if (Boolean(this.project.readme)) {
+    if (preserveReadme) {
       this.urls.push(
         new UrlMapping(
-          this.preserveModulesPage ? 'readme_.md' : entryFileName,
+          preserveModulesPage ? 'readme_.md' : entryFileName,
           this.project,
           this.theme.readmeTemplate,
         ),
@@ -72,7 +71,7 @@ export class UrlsContext {
     } else {
       this.urls.push(
         new UrlMapping(
-          this.preserveModulesPage ? indexFilename : entryFileName,
+          preserveModulesPage ? indexFilename : entryFileName,
           this.project,
           this.theme.projectTemplate,
         ),

diff --git a/packages/typedoc-plugin-markdown/test/__utils__/fixture-config.ts b/packages/typedoc-plugin-markdown/test/__utils__/fixture-config.ts
@@ -12,6 +12,7 @@ export enum FixtureEntryPoints {
   Groups = '/src/groups/**/*.ts',
   Comments = '/src/comments/index.ts',
   EntryFiles = '/src/entryfiles/*',
+  Readme = '/src/readme/index.ts',
 }
 
 export enum FixtureOutputDir {
@@ -20,6 +21,7 @@ export enum FixtureOutputDir {
   Groups = 'groups',
   Comments = 'comments',
   EntryFiles = 'entryfiles',
+  Readme = 'readme',
 }
 
 export const FIXTURES: Fixture[] = [
@@ -114,4 +116,10 @@ export const FIXTURES: Fixture[] = [
     commonOptions: { entryModule: 'entry-module', hideGenerator: true },
     options: [{ entryFileName: 'README.md' }, { readme: 'none' }],
   },
+  {
+    outDir: FixtureOutputDir.Readme,
+    entryPoints: FixtureEntryPoints.Readme,
+    commonOptions: {},
+    options: [{ disableSources: true, hideGenerator: true, mergeReadme: true }],
+  },
 ];
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/readme.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/readme.spec.ts.snap
@@ -0,0 +1,63 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Readmes should get merged readme for members: (Output File Strategy "members") (Option Group "1") 1`] = `
+"**typedoc-stubs** • [Exports](index.md)
+
+***
+
+# MY README
+
+> Some block quote
+
+Some text.
+
+## Readme heading
+
+Some text.
+
+## typedoc-stubs
+
+Module commments
+
+### Functions
+
+- [someFunction](functions/someFunction.md)
+"
+`;
+
+exports[`Readmes should get merged readme for modules: (Output File Strategy "modules") (Option Group "1") 1`] = `
+"**typedoc-stubs** • Exports
+
+***
+
+# MY README
+
+> Some block quote
+
+Some text.
+
+## Contents
+
+- [Readme heading](index.md#readme-heading)
+- [typedoc-stubs](index.md#typedoc-stubs)
+  - [Functions](index.md#functions)
+
+## Readme heading
+
+Some text.
+
+## typedoc-stubs
+
+Module commments
+
+### Functions
+
+#### someFunction()
+
+> **someFunction**(): \`void\`
+
+##### Returns
+
+\`void\`
+"
+`;
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
@@ -196,6 +196,19 @@ exports[`Urls should gets Urls for packages entry points: outputFileStrategy: mo
 ]
 `;
 
+exports[`Urls should gets Urls for readme options: outputFileStrategy: members 1`] = `
+[
+  "functions/someFunction.md",
+  "index.md",
+]
+`;
+
+exports[`Urls should gets Urls for readme options: outputFileStrategy: modules 1`] = `
+[
+  "index.md",
+]
+`;
+
 exports[`Urls should gets Urls for single entry points: outputFileStrategy: members 1`] = `
 [
   "classes/AbstractClass.md",

diff --git a/packages/typedoc-plugin-markdown/test/specs/readme.spec.ts b/packages/typedoc-plugin-markdown/test/specs/readme.spec.ts
@@ -0,0 +1,23 @@
+import {
+  FixtureOutputDir,
+  FixtureOutputFileStrategy,
+} from '../__utils__/fixture-config';
+import { expectFileToEqual } from '../__utils__/helpers';
+
+describe(`Readmes`, () => {
+  test(`should get merged readme for members`, () => {
+    expectFileToEqual(
+      FixtureOutputDir.Readme,
+      FixtureOutputFileStrategy.Members,
+      ['index.md'],
+    );
+  });
+
+  test(`should get merged readme for modules`, () => {
+    expectFileToEqual(
+      FixtureOutputDir.Readme,
+      FixtureOutputFileStrategy.Modules,
+      ['index.md'],
+    );
+  });
+});
diff --git a/packages/typedoc-plugin-markdown/test/specs/urls.spec.ts b/packages/typedoc-plugin-markdown/test/specs/urls.spec.ts
@@ -32,4 +32,11 @@ describe(`Urls`, () => {
       FixtureOutputFileStrategy.Modules,
     ]);
   });
+
+  test(`should gets Urls for readme options`, () => {
+    expectUrlsToEqual(FixtureOutputDir.Readme, [
+      FixtureOutputFileStrategy.Members,
+      FixtureOutputFileStrategy.Modules,
+    ]);
+  });
 });
diff --git a/stubs/src/readme/index.ts b/stubs/src/readme/index.ts
@@ -0,0 +1,7 @@
+/**
+ * Module commments
+ *
+ * @module
+ */
+
+export function someFunction() {}