feat: Added --mergeReadme option

typedoc2md · Oct 28, 2023 · 99ec601 · 99ec601
1 parent 7bdffb0
commit 99ec601
Show file tree

Hide file tree

Showing 35 changed files with 534 additions and 298 deletions.
diff --git a/examples/docusaurus/docusaurus.config.js b/examples/docusaurus/docusaurus.config.js
@@ -43,6 +43,29 @@ const config = {
   },
 
   plugins: [
+    [
+      docusaurusPlugin,
+      {
+        id: 'query-builder',
+        entryPoints: [
+          '../../../usecases/react-querybuilder-v4/packages/react-querybuilder',
+          '../../../usecases/react-querybuilder-v4/packages/antd',
+          '../../../usecases/react-querybuilder-v4/packages/blueprint',
+          '../../../usecases/react-querybuilder-v4/packages/bootstrap',
+          '../../../usecases/react-querybuilder-v4/packages/bulma',
+          '../../../usecases/react-querybuilder-v4/packages/chakra',
+          '../../../usecases/react-querybuilder-v4/packages/dnd',
+          '../../../usecases/react-querybuilder-v4/packages/fluent',
+          '../../../usecases/react-querybuilder-v4/packages/mantine',
+          '../../../usecases/react-querybuilder-v4/packages/material',
+          '../../../usecases/react-querybuilder-v4/packages/native',
+        ],
+        out: './docs/query-builder',
+        readme: '../../../usecases/react-querybuilder-v4/website/_API_INDEX.md',
+        entryPointStrategy: 'packages',
+        cleanOutputDir: true,
+      },
+    ],
     [
       docusaurusPlugin,
       {

diff --git a/examples/docusaurus/sidebars.js b/examples/docusaurus/sidebars.js
@@ -16,6 +16,15 @@ const sidebars = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
 
   typedocSidebar: [
+    {
+      type: 'category',
+      label: 'Query Builder API',
+      link: {
+        type: 'doc',
+        id: 'query-builder/index',
+      },
+      items: require('./docs/query-builder/typedoc-sidebar.cjs'),
+    },
     {
       type: 'category',
       label: 'API',

diff --git a/packages/typedoc-plugin-markdown/README.md b/packages/typedoc-plugin-markdown/README.md
@@ -4,7 +4,7 @@
 
 > **Please note this pre-release version may contain breaking changes within the same semantic version.**
 
-A plugin for [TypeDoc](https://typedoc.org) that renders TypeScript API documentation as Markdown.
+A plugin for [TypeDoc](https://typedoc.org) that renders TypeScript API documentation as Markdown. [MDX 2+](https://mdxjs.com/) and [GFM](https://github.github.com/gfm/) compliant.
 
 ## Contents
 
@@ -29,54 +29,63 @@ npm install typedoc typedoc-plugin-markdown@next --save-dev
 
 ## Usage
 
-Plugins are loaded by using the `plugin` configuration option:
+Plugins are loaded by using the TypeDoc `plugin` configuration option:
 
 ```bash
 typedoc --plugin typedoc-plugin-markdown
 ```
 
-Please see <https://typedoc.org/options/configuration>.
+For general TypeDoc configuration usage please see <https://typedoc.org/options/configuration>.
 
 ## Options
 
-### TypeDoc options
+### TypeDoc Options
 
 All of TypeDoc's [Configuration](https://typedoc.org/options/configuration/), [Input](https://typedoc.org/options/input/) and [Organization](https://typedoc.org/options/organization/) options are respected as they are executed at the conversion phase of the project.
 
-TypeDoc's [Output](https://typedoc.org/options/output/) options are on the whole only relevant to the HTML theme and the majority are ignored by this plugin. Supported Output options are [`out`](https://typedoc.org/options/output/#out), `cleanOutputDir`.
+TypeDoc's [Output](https://typedoc.org/options/output/) options are on the whole only relevant to the HTML theme and the majority are ignored by this plugin.
+
+Supported Output options are: [`--out`](https://typedoc.org/options/output/#out), [`--cleanOutputDir`](https://typedoc.org/options/output/#cleanoutputdir).
 
 ### Plugin Options
 
-This plugin exposes additional options. Please see [Options Guide](./docs/guides/options.md) for detailed usage.
+This plugin exposes several additional options. Please see [Plugin Options](./docs/plugin-options.md) for detailed usage.
 
 #### File output options
 
-* [`--outputFileStrategy`](./docs/guides/options.md#--outputfilestrategy)
-* [`--membersWithOwnFile`](./docs/guides/options.md#--memberswithownfile)
-* [`--entryFileName`](./docs/guides/options.md#--entryfilename)
+Options that configure how files are generated.
+
+* [`--outputFileStrategy`](./docs/plugin-options.md#--outputfilestrategy)
+* [`--membersWithOwnFile`](./docs/plugin-options.md#--memberswithownfile)
+* [`--entryFileName`](./docs/plugin-options.md#--entryfilename)
+* [`--mergeReadme`](./docs/plugin-options.md#--mergereadme)
 
 #### Structure and formatting options
 
-* [`--hidePageHeader`](./docs/guides/options.md#--hidepageheader)
-* [`--hidePageTitle`](./docs/guides/options.md#--hidepagetitle)
-* [`--hideBreadcrumbs`](./docs/guides/options.md#--hidebreadcrumbs)
-* [`--hideInPageTOC`](./docs/guides/options.md#--hideinpagetoc)
-* [`--indexPageTitle`](./docs/guides/options.md#--indexpagetitle)
-* [`--memberPageTitle`](./docs/guides/options.md#--memberpagetitle)
-* [`--excludeGroups`](./docs/guides/options.md#--excludegroups)
-* [`--useCodeBlocks`](./docs/guides/options.md#--usecodeblocks)
-* [`--expandObjects`](./docs/guides/options.md#--expandobjects)
-* [`--parametersFormat`](./docs/guides/options.md#--parametersformat)
-* [`--propertiesFormat`](./docs/guides/options.md#--propertiesformat)
-* [`--enumMembersFormat`](./docs/guides/options.md#--enummembersformat)
-* [`--typeDeclarationFormat`](./docs/guides/options.md#--typedeclarationformat)
-* [`--indexFormat`](./docs/guides/options.md#--indexformat)
+Options that alter the format and structure of pages.
+
+* [`--hidePageHeader`](./docs/plugin-options.md#--hidepageheader)
+* [`--hidePageTitle`](./docs/plugin-options.md#--hidepagetitle)
+* [`--hideBreadcrumbs`](./docs/plugin-options.md#--hidebreadcrumbs)
+* [`--hideInPageTOC`](./docs/plugin-options.md#--hideinpagetoc)
+* [`--indexPageTitle`](./docs/plugin-options.md#--indexpagetitle)
+* [`--memberPageTitle`](./docs/plugin-options.md#--memberpagetitle)
+* [`--excludeGroups`](./docs/plugin-options.md#--excludegroups)
+* [`--useCodeBlocks`](./docs/plugin-options.md#--usecodeblocks)
+* [`--expandObjects`](./docs/plugin-options.md#--expandobjects)
+* [`--parametersFormat`](./docs/plugin-options.md#--parametersformat)
+* [`--propertiesFormat`](./docs/plugin-options.md#--propertiesformat)
+* [`--enumMembersFormat`](./docs/plugin-options.md#--enummembersformat)
+* [`--typeDeclarationFormat`](./docs/plugin-options.md#--typedeclarationformat)
+* [`--indexFormat`](./docs/plugin-options.md#--indexformat)
 
 #### Utility options
 
-* [`--preserveAnchorCasing`](./docs/guides/options.md#--preserveanchorcasing)
-* [`--anchorPrefix`](./docs/guides/options.md#--anchorprefix)
-* [`--namedAnchors`](./docs/guides/options.md#--namedanchors)
+Options that configure additional functionality.
+
+* [`--preserveAnchorCasing`](./docs/plugin-options.md#--preserveanchorcasing)
+* [`--anchorPrefix`](./docs/plugin-options.md#--anchorprefix)
+* [`--namedAnchors`](./docs/plugin-options.md#--namedanchors)
 
 ## Contributing
 

diff --git a/...lugin-markdown/docs/guides/customizing.md → ...pedoc-plugin-markdown/docs/customizing.md b/...lugin-markdown/docs/guides/customizing.md → ...pedoc-plugin-markdown/docs/customizing.md
diff --git a/...oc-plugin-markdown/docs/guides/options.md → ...oc-plugin-markdown/docs/plugin-options.md b/...oc-plugin-markdown/docs/guides/options.md → ...oc-plugin-markdown/docs/plugin-options.md
@@ -1,11 +1,14 @@
-# Options Guide
+# Plugin Options
+
+This document describes all the additional options exposed by the plugin.
 
 ## Contents
 
 * [File output options](#file-output-options)
   * [`--outputFileStrategy`](#--outputfilestrategy)
   * [`--membersWithOwnFile`](#--memberswithownfile)
   * [`--entryFileName`](#--entryfilename)
+  * [`--mergeReadme`](#--mergereadme)
 * [Structure and formatting options](#structure-and-formatting-options)
   * [`--hidePageHeader`](#--hidepageheader)
   * [`--hidePageTitle`](#--hidepagetitle)
@@ -28,6 +31,8 @@
 
 ## File output options
 
+Options that configure how files are generated.
+
 ### `--outputFileStrategy`
 
 Determines how output files are generated. Defaults to `"members"`.
@@ -145,8 +150,29 @@ B. If a readme file is NOT resolved (when `readme` = `none`), then the index pag
 
 ***
 
+### `--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 index page is created. This option prepends the readme file into the index page creating a single documentation entrypoint.
+
+* This option is ignored when `readme` is set to `none`.
+* `--indexPageTitle` is ignored.
+
+[↑ Top](#options-guide)
+
+***
+
 ## Structure and formatting options
 
+Options that alter the format and structure of pages.
+
 ### `--hidePageHeader`
 
 Do not print page header. Defaults to `false`.
@@ -185,7 +211,7 @@ Do not print breadcrumbs. Defaults to `false`.
 
 ### `--hideInPageTOC`
 
-Do not render in-page TOC/Index items. Defaults to `false`.
+Do not render in-page TOC items. Defaults to `false`.
 
 ```shell
 --hideInPageTOC <boolean>
@@ -215,7 +241,7 @@ Defaults to `{projectName}` - a placeholder that renders the project name and ve
 
 ### `--memberPageTitle`
 
-The template for displaying page titles of members. Defaults to `"{kind}: {name}"`.
+The page title of members. Defaults to `"{kind}: {name}"`.
 
 ```shell
 --memberPageTitle <string>
@@ -225,10 +251,16 @@ The template for displaying page titles of members. Defaults to `"{kind}: {name}
 
 Provides a mechanism to change the page title of members.
 
-Supports `{kind}` and `{name}` placeholders.
+Supports `{name}` and `{kind}` placeholders.
 
 e.g "Class: MyClassName"
 
+For example to display member name only:
+
+```json
+memberPageTitle: "{name}"
+```
+
 [↑ Top](#options-guide)
 
 ***
@@ -361,6 +393,8 @@ This determines wheter to display index items either as a simple lists or in a t
 
 ## Utility options
 
+Options that configure additional functionality.
+
 ### `--preserveAnchorCasing`
 
 Preserve anchor casing when generating links. Defaults to `false`.

diff --git a/packages/typedoc-plugin-markdown/docs/readme-usage.md b/packages/typedoc-plugin-markdown/docs/readme-usage.md
@@ -0,0 +1,18 @@
+# Readme Usage
+
+TypeDoc by default will attempt to resolve a projects Readme file. In addition TypeDoc's a path to a specfic file can be provided using the `--readme` option. This can be set to `none` to disable Readme page generation.
+
+## Injecting the TypeDoc index page
+
+When a readme file is resolved a separate index file is generated acting as the root into the generated documentation.
+
+<!--
+## Using Remark
+
+To parse files generated by this plugin with Remark please see [typedoc-plugin-remark]().
+
+Recommened remark plugins that work well with Readme pages are:
+
+- [remarkTOC]()
+- [remarkGithub]()
+-->
diff --git a/packages/typedoc-plugin-markdown/package.json b/packages/typedoc-plugin-markdown/package.json
@@ -15,7 +15,7 @@
     "test": "npm-run-all test:*",
     "test:lint-md": "node test/__scripts__/lint.md.mjs",
     "test:lint-mdx": "node test/__scripts__/lint.mdx.mjs",
-    "test:jest": "jest",
+    "test:jest": "jest --updateSnapshot",
     "build-and-test": "npm run build && npm run test",
     "api-docs": "npm run build && typedoc --options ./typedoc.api.js --out ./docs/api",
     "task:docs": "node scripts/docs/docs.mjs",

diff --git a/packages/typedoc-plugin-markdown/scripts/docs/docs.mjs b/packages/typedoc-plugin-markdown/scripts/docs/docs.mjs
@@ -24,7 +24,7 @@ async function readmePage() {
 }
 
 async function optionsPage() {
-  const file = await read('./docs/guides/options.md');
+  const file = await read('./docs/plugin-options.md');
   const processor = await remark().use(remarkGfm).use(guideOptions);
   const vfile = await remark()
     .use(remarkToc, { heading: 'Contents', maxDepth: 3 })

diff --git a/packages/typedoc-plugin-markdown/scripts/docs/remark/guide-options.mjs b/packages/typedoc-plugin-markdown/scripts/docs/remark/guide-options.mjs
@@ -25,7 +25,6 @@ function parseOptions(tree, key) {
 
 function getMarkdown(key) {
   const md = [INTRO_MAP[key]];
-
   groupedConfig[key].forEach((config, i) => {
     md.push(`### \`--${config.name}\``);
     md.push(`${config.help} Defaults to \`${getDefaultValue(config)}\`.`);

diff --git a/packages/typedoc-plugin-markdown/scripts/docs/remark/readme-options.mjs b/packages/typedoc-plugin-markdown/scripts/docs/remark/readme-options.mjs
@@ -28,7 +28,7 @@ function getMarkdown(key) {
     .map((config) => {
       return `- [\`--${
         config.name
-      }\`](./docs/guides/options.md#--${config.name.toLowerCase()})`;
+      }\`](./docs/plugin-options.md#--${config.name.toLowerCase()})`;
     })
     .join('\n');
   return [intro, list].join('\n\n');

diff --git a/packages/typedoc-plugin-markdown/scripts/utils/options.utils.mjs b/packages/typedoc-plugin-markdown/scripts/utils/options.utils.mjs
@@ -48,7 +48,7 @@ export const TITLE_MAP = {
 };
 
 export const INTRO_MAP = {
-  fileOutput: '',
-  ui: '',
-  other: '',
+  fileOutput: 'Options that configure how files are generated.',
+  ui: 'Options that alter the format and structure of pages.',
+  other: 'Options that configure additional functionality.',
 };
diff --git a/packages/typedoc-plugin-markdown/src/plugin/options/config.ts b/packages/typedoc-plugin-markdown/src/plugin/options/config.ts
@@ -55,7 +55,7 @@ import {
  *
  * @category fileOutput
  */
-export const mdOutputFileStrategy: DeclarationOption = {
+export const outputFileStrategy: DeclarationOption = {
   name: 'outputFileStrategy',
   help: 'Determines how output files are generated.',
   type: ParameterType.Map,
@@ -123,6 +123,22 @@ export const entryFileName: DeclarationOption = {
   defaultValue: 'README.md',
 };
 
+/**
+ * By default when a readme file is resolved, a seperate index page is created. This option prepends the readme file into the index page creating a single documentation entrypoint.
+ *
+ * - This option is ignored when `readme` is set to `none`.
+ * - `--indexPageTitle` is ignored.
+ *
+ * @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
  */
@@ -158,7 +174,7 @@ export const hideBreadcrumbs: DeclarationOption = {
  */
 export const hideInPageTOC: DeclarationOption = {
   name: 'hideInPageTOC',
-  help: 'Do not render in-page TOC/Index items.',
+  help: 'Do not render in-page TOC items.',
   type: ParameterType.Boolean,
   defaultValue: false,
 };
@@ -180,10 +196,16 @@ export const indexPageTitle: DeclarationOption = {
 /**
  * Provides a mechanism to change the page title of members.
  *
- * Supports `{kind}` and `{name}` placeholders.
+ * Supports `{name}` and `{kind}` placeholders.
  *
  * e.g "Class: MyClassName"
  *
+ * For example to display member name only:
+ *
+ * ```json
+ * memberPageTitle: "{name}"
+ * ```
+ *
  * @category ui
  */
 export const memberPageTitle: DeclarationOption = {

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

diff --git a/packages/typedoc-plugin-markdown/src/theme/helpers.ts b/packages/typedoc-plugin-markdown/src/theme/helpers.ts
@@ -245,3 +245,7 @@ export function getIndexFileName(project: ProjectReflection) {
   );
   return isModules ? 'modules.md' : 'exports.md';
 }
+
+export function hasReadme(project: ProjectReflection) {
+  return Boolean(project.readme);
+}