feat: Extract frontmatter logic into seperate TypeDoc plugin

typedoc2md · May 3, 2023 · cdec172 · cdec172
1 parent db5ebc3
commit cdec172
Show file tree

Hide file tree

Showing 18 changed files with 61 additions and 437 deletions.
diff --git a/.changeset/perfect-ligers-help.md b/.changeset/perfect-ligers-help.md
@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Extract frontmatter logic into seperate TypeDoc plugin
diff --git a/examples/docusaurus/docusaurus.config.js b/examples/docusaurus/docusaurus.config.js
@@ -42,6 +42,11 @@ const config = {
         cleanOutputDir: true,
         groupByKinds: true,
         longPageTitles: true,
+        plugin: ['typedoc-plugin-frontmatter'],
+        frontmatterGlobals: {
+          pagination_prev: null,
+          pagination_next: null,
+        },
       },
     ],
     [

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -29,6 +29,7 @@
     "ts-morph": "^18.0.0",
     "ts-node": "^10.9.1",
     "typedoc": "^0.24.4",
+    "typedoc-plugin-frontmatter": "^0.0.2",
     "typedoc-plugin-mdn-links": "^3.0.3",
     "typescript": "^5.0.4"
   }

diff --git a/packages/typedoc-plugin-markdown/README.md b/packages/typedoc-plugin-markdown/README.md
@@ -72,19 +72,6 @@ See [File output options](./docs/file-output-options.md) for further documentati
 - **`--enumMembersFormat`**<br>
   Specify the render style of Enum members. Expected values [`list`, `table`]. Defaults to `list`.
 
-### Frontmatter options
-
-See [Front matter options](./docs/frontmatter.md) for further documentation.
-
-- **`--enableFrontmatter`**<br>
-  Prepend output with a YAML front matter block. Defaults to `false`.
-- **`--frontmatterTags`**<br>
-  Specify which file comment tags should be added to front matter variables (as an array).
-- **`--frontmatterGlobals`**<br>
-  Specify global static variables to be added to all front matter blocks (as an object).
-- **`--frontmatterNamingConvention`**<br>
-  Specify the naming convention of front matter variables. Expected values [`camelCase`, `snakeCase`,`kebabCase`]. Defaults to `camelCase`.
-
 ### Utility options
 
 - **`--anchorFormat`**<br>
@@ -94,9 +81,13 @@ See [Front matter options](./docs/frontmatter.md) for further documentation.
 - **`--baseUrl`**<br>
   Specifies the base url for internal link. If omitted all urls will be relative. Defaults to `.`
 
+## Frontmatter
+
+If frontmatter is required for adding further metadata please use [typedoc-plugin-frontmatter](https://github.com/tgreyuk/typedoc-plugin-frontmatter)
+
 ## Output formatting (Prettier)
 
-Generated Markdown is now parsed with [Prettier](https://prettier.io/) which is backed by the remark-parse package. This does require an additional peer dependency but has several benefits:
+Generated Markdown is now parsed with [Prettier](https://prettier.io/) which is backed by the remark-parse package. Parsing documents with Prettier has several benefits:
 
 - Produces a consistent format.
 - Remove unnecessary escape characters.
@@ -107,7 +98,6 @@ Any [prettier configuration](https://prettier.io/docs/en/configuration.html) fil
 ## Further Documentation
 
 - [File output options](./docs/file-output-options.md)
-- [Frontmatter options](./docs/frontmatter.md)
 - [Readme files](./docs/readme-files.md)
 
 ## License

diff --git a/packages/typedoc-plugin-markdown/docs/frontmatter.md b/packages/typedoc-plugin-markdown/docs/frontmatter.md
diff --git a/packages/typedoc-plugin-markdown/package.json b/packages/typedoc-plugin-markdown/package.json
@@ -17,7 +17,7 @@
     "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 --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: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:html": "typedoc --options ../../stubs/typedoc.json --out ./out/html"
   },
   "author": "Thomas Grey",

diff --git a/packages/typedoc-plugin-markdown/src/models.ts b/packages/typedoc-plugin-markdown/src/models.ts
@@ -3,13 +3,9 @@ import { ReflectionKind, TypeDocOptionMap } from 'typedoc';
 export interface TypedocPluginMarkdownOptions extends TypeDocOptionMap {
   anchorFormat: AnchorFormat;
   baseUrl: string;
-  enableFrontmatter: boolean;
   entryDocument: string;
   enumMembersFormat: DataFormatStyle;
   flattenOutputFiles: boolean;
-  frontmatterTags: string[];
-  frontmatterGlobals: FrontmatterGlobals;
-  frontmatterNamingConvention: FrontmatterNamingConvention;
   groupByKinds: boolean;
   hideBreadcrumbs: boolean;
   hideInPageTOC: boolean;

diff --git a/packages/typedoc-plugin-markdown/src/options.ts b/packages/typedoc-plugin-markdown/src/options.ts
@@ -133,49 +133,15 @@ export function defineOptions(app: Application) {
   });
 
   /**
-   * Frontmatter options
+   * Frontmatter options (TO BE DELETED)
    */
   app.options.addDeclaration({
     name: 'enableFrontmatter',
-    help: '[Markdown Plugin] Prepend frontmatter to output.',
+    help: '[Markdown Plugin] Removed (please use typedoc-plugin-fronmatter)',
     type: ParameterType.Boolean,
     defaultValue: false,
   });
 
-  app.options.addDeclaration({
-    name: 'frontmatterTags',
-    help: '[Markdown Plugin] Specify which file comment tags should be added to frontmatter.',
-    type: ParameterType.Array,
-    defaultValue: [],
-  });
-
-  app.options.addDeclaration({
-    name: 'frontmatterGlobals',
-    help: '[Markdown Plugin] Specify static variables to be added to all frontmatter.',
-    type: ParameterType.Mixed,
-    defaultValue: {},
-  });
-
-  app.options.addDeclaration({
-    name: 'frontmatterNamingConvention',
-    help: '[Markdown Plugin] Specify the naming convention of front matter variables.',
-    type: ParameterType.String,
-    defaultValue: 'camelCase',
-    validate: (option) => {
-      const availableValues = [
-        'camelCase',
-        'snakeCase',
-        'kebabCase',
-        'pascalCase',
-      ];
-      if (!availableValues.includes(option)) {
-        throw new Error(
-          `Unexpected value for frontmatterNamingConvention, the expected value is one of 'camelCase', 'snakeCase','kebabCase','pascalCase'`,
-        );
-      }
-    },
-  });
-
   /**
    * Utility options
    */