feat(frontmatter): expose "yamlStringifyOptions" option

Author: tgreyuk

.changeset/config.json

@@ -13,7 +13,6 @@
   "ignore": [
     "@devtools/*",
     "typedoc-github-wiki-theme",
-    "typedoc-gitlab-wiki-theme",
-    "typedoc-plugin-frontmatter"
+    "typedoc-gitlab-wiki-theme"
   ]
 }

.changeset/curvy-radios-wash.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-frontmatter': minor
+---
+
+- Expose "yamlStringifyOptions" option (#771).

docs/pages/plugins/frontmatter/options.mdx

@@ -99,6 +99,10 @@ description: A description that will be added to frontmatter.
 
 > Accepts a boolean value. Defaults to `false`.
 
+By default tags defined in `frontmatterCommentTags` are removed from final output.
+
+Use this option to preserve the tags in the output.
+
 ```json filename="typedoc.json"
 {
   "preserveFrontmatterCommentTags": false
@@ -122,3 +126,23 @@ This option can configure the output style of frontmatter variables when written
   "frontmatterNamingConvention": "camelCase"
 }
 ```
+
+## yamlStringifyOptions
+
+<Callout emoji="💡">Options to pass into `yaml.stringify()`.</Callout>
+
+> Accepts a key/value object.
+
+Provides additional options to control how YAML is internally serialized using
+the `yaml.stringify` method from the [YAML](https://eemeli.org/yaml/#yaml) library.
+
+For available options, see
+[YAML ToString Options](https://eemeli.org/yaml/#tostring-options).
+
+```json filename="typedoc.json"
+{
+  "yamlStringifyOptions": {
+    "lineWidth": 0
+  }
+}
+```

package-lock.json

@@ -31,7 +31,7 @@
   },
   "homepage": "https://typedoc-plugin-markdown.org/plugins/frontmatter",
   "dependencies": {
-    "yaml": "^2.3.4"
+    "yaml": "^2.7.0"
   },
   "peerDependencies": {
     "typedoc-plugin-markdown": ">=4.4.2"

packages/typedoc-plugin-frontmatter/package.json

@@ -1,5 +1,7 @@
 // THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY.
 import { ManuallyValidatedOption } from 'typedoc';
+import { ToStringOptions } from 'yaml';
+
 declare module 'typedoc' {
   export interface TypeDocOptionMap {
     frontmatterCommentTags: string[];
@@ -8,5 +10,6 @@ declare module 'typedoc' {
     indexFrontmatter: ManuallyValidatedOption<Record<string, any>>;
     preserveFrontmatterCommentTags: boolean;
     readmeFrontmatter: ManuallyValidatedOption<Record<string, any>>;
+    yamlStringifyOptions: ManuallyValidatedOption<ToStringOptions>;
   }
 }

packages/typedoc-plugin-frontmatter/src/_typedoc.d.ts

@@ -60,8 +60,14 @@ export function load(app: MarkdownApplication) {
     MarkdownPageEvent.END,
     (page: MarkdownPageEvent<ProjectReflection | DeclarationReflection>) => {
       if (page.frontmatter && Object.keys(page.frontmatter)?.length) {
+        const yamlStringifyOptions = app.options.getValue(
+          'yamlStringifyOptions',
+        );
         page.contents = page?.contents
-          ?.replace(/^/, `---\n${yaml.stringify(page.frontmatter)}---\n\n`)
+          ?.replace(
+            /^/,
+            `---\n${yaml.stringify(page.frontmatter, yamlStringifyOptions)}---\n\n`,
+          )
           .replace(/[\r\n]{3,}/g, '\n\n');
       }
     },

packages/typedoc-plugin-frontmatter/src/index.ts

@@ -90,6 +90,11 @@ export const frontmatterCommentTags: Partial<DeclarationOption> = {
   type: ParameterType.Array,
 };
 
+/**
+ * By default tags defined in `frontmatterCommentTags` are removed from final output.
+ *
+ * Use this option to preserve the tags in the output.
+ */
 export const preserveFrontmatterCommentTags: Partial<DeclarationOption> = {
   help: 'Preserve tags defined in frontmatter block tags in output.',
   type: ParameterType.Boolean,
@@ -107,3 +112,18 @@ export const frontmatterNamingConvention: Partial<DeclarationOption> = {
   map: FrontmatterNamingConvention,
   defaultValue: FrontmatterNamingConvention.CamelCase,
 };
+
+/**
+ * Provides additional options to control how YAML is internally serialized using
+ * the `yaml.stringify` method from the [YAML](https://eemeli.org/yaml/#yaml) library.
+ *
+ * For available options, see
+ * [YAML ToString Options](https://eemeli.org/yaml/#tostring-options).
+ *
+ * @example { "lineWidth": 0 }
+ */
+export const yamlStringifyOptions: Partial<DeclarationOption> = {
+  help: 'Options to pass into `yaml.stringify()`.',
+  type: ParameterType.Object,
+  defaultValue: {},
+};

packages/typedoc-plugin-frontmatter/src/options/declarations.ts

@@ -1,6 +1,7 @@
 /*
  * THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY
  */
+import { ToStringOptions } from 'yaml';
 /**
  * Describes the options declared by the plugin.
  */
@@ -34,4 +35,9 @@ export interface PluginOptions {
    * Specify static variables to be added to the readme page only.
    */
   readmeFrontmatter: Record<string, any>;
+
+  /**
+   * Options to pass into `yaml.stringify()`.
+   */
+  yamlStringifyOptions: ToStringOptions;
 }

packages/typedoc-plugin-frontmatter/src/types/options.ts

@@ -12,6 +12,7 @@ fs.removeSync(`./test/out`);
 const fixtures = [
   { options: 'typedoc-options.cjs', outDir: 'options' },
   { options: 'typedoc-options-2.cjs', outDir: 'options-2' },
+  { options: 'typedoc-options-3.cjs', outDir: 'options-3' },
   { options: 'typedoc-base.json', outDir: 'no-data' },
 ];
 

packages/typedoc-plugin-frontmatter/test/__scripts__/prepare.ts

@@ -1,5 +1,18 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`Options: YAML should accept yaml stringify options 1`] = `
+"---
+veryLong: This is a long string that would normally wrap over multiple lines when the text exceeds a certain length.
+---
+
+# typedoc-plugin-frontmatter
+
+## Interfaces
+
+- [SomeInterface](interfaces/SomeInterface.md)
+"
+`;
+
 exports[`Options: YAML should prepend frontmatter 1`] = `
 "---
 title: SomeInterface
@@ -18,6 +31,8 @@ exports[`Options: YAML should prepend frontmatter for readme page 1`] = `
 "---
 title: typedoc-plugin-frontmatter
 layout: blog
+veryLong: This is a long string that would normally wrap over multiple lines
+  when the text exceeds a certain length.
 navOrder: 1
 hide: true
 onReadme: true
@@ -31,6 +46,8 @@ exports[`Options: YAML should prepend frontmatter to index page 1`] = `
 "---
 title: typedoc-plugin-frontmatter
 layout: blog
+veryLong: This is a long string that would normally wrap over multiple lines
+  when the text exceeds a certain length.
 navOrder: 1
 hide: true
 onIndex: true
@@ -48,6 +65,8 @@ exports[`Options: YAML should prepend frontmatter with preserved tags 1`] = `
 "---
 title: SomeInterface
 layout: blog
+veryLong: This is a long string that would normally wrap over multiple lines
+  when the text exceeds a certain length.
 navOrder: 1
 hide: true
 tagOne: 0

packages/typedoc-plugin-frontmatter/test/specs/__snapshots__/options.spec.ts.snap

@@ -36,5 +36,12 @@ describe(`Options:`, () => {
         .toString();
       expect(pageContent).toMatchSnapshot();
     });
+
+    test(`should accept yaml stringify options`, async () => {
+      const pageContent = fs
+        .readFileSync(path.join(__dirname, '../out/options-3/README.md'))
+        .toString();
+      expect(pageContent).toMatchSnapshot();
+    });
   });
 });

packages/typedoc-plugin-frontmatter/test/specs/options.spec.ts

@@ -22,6 +22,8 @@ module.exports = {
   },
   frontmatterGlobals: {
     layout: 'blog',
+    veryLong:
+      'This is a long string that would normally wrap over multiple lines when the text exceeds a certain length.',
     navOrder: 1,
     hide: true,
   },

packages/typedoc-plugin-frontmatter/test/typedoc-options-2.cjs

@@ -0,0 +1,19 @@
+// @ts-check
+
+/** @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions & import('typedoc-plugin-frontmatter').PluginOptions} */
+module.exports = {
+  entryPoints: ['./stubs.ts'],
+  tsconfig: '../tsconfig.test.json',
+  readme: 'none',
+  plugin: ['typedoc-plugin-markdown', 'typedoc-plugin-frontmatter'],
+  hidePageHeader: true,
+  hideBreadcrumbs: true,
+  frontmatterGlobals: {
+    veryLong:
+      'This is a long string that would normally wrap over multiple lines when the text exceeds a certain length.',
+  },
+  yamlStringifyOptions: {
+    lineWidth: 0,
+  },
+  disableSources: true,
+};