chore(remark): normalize tables output

typedoc2md · Jun 15, 2024 · 57aebaf · 57aebaf
1 parent a8f5385
commit 57aebaf
Show file tree

Hide file tree

Showing 8 changed files with 195 additions and 25 deletions.
diff --git a/packages/typedoc-plugin-remark/lint.mdx.mjs b/packages/typedoc-plugin-remark/lint.mdx.mjs
@@ -0,0 +1,44 @@
+import { consola } from 'consola';
+import { glob } from 'glob';
+import { remark } from 'remark';
+import remarkMdx from 'remark-mdx';
+import { read } from 'to-vfile';
+
+const timeStart = new Date().getTime();
+
+let error = false;
+
+consola.start(`Begin linting MDX...`);
+
+lintMdx();
+
+async function lintMdx() {
+  const mdFiles = await glob(`./test/out/**/*.md`);
+
+  if (mdFiles.length === 0) {
+    consola.error('No markdown files found');
+    throw new Error();
+  }
+
+  mdFiles.forEach(async (file) => {
+    const vfile = await read(file);
+    try {
+      await remark().use(remarkMdx).processSync(vfile);
+    } catch (e) {
+      error = true;
+      consola.error(`Error linting MDX on file ${file}`);
+      throw new Error(e);
+    }
+  });
+}
+
+process.on('exit', () => {
+  if (!error) {
+    consola.success(
+      `Finished linting MDX in ${(
+        (new Date().getTime() - timeStart) /
+        1000
+      ).toFixed(2)} seconds`,
+    );
+  }
+});
diff --git a/packages/typedoc-plugin-remark/package.json b/packages/typedoc-plugin-remark/package.json
@@ -11,9 +11,9 @@
     "prepublishOnly": "npm run lint && npm run build",
     "prebuild": "rm -rf dist && prebuild-options",
     "build": "tsc",
-    "postbuild": "copyfiles --up 1 ./src/**/*.cjs ./dist/",
+    "postbuild": "copyfiles --up 1 ./src/**/*.cjs ./src/**/*.mjs ./dist/",
     "pretest": "ts-node ./test/__scripts__/prepare.ts",
-    "test": "jest",
+    "test": "node ./lint.mdx.mjs && jest",
     "test:update": "npm run build && npm run test -- -u"
   },
   "repository": {

diff --git a/packages/typedoc-plugin-remark/src/normalize-tables.mjs b/packages/typedoc-plugin-remark/src/normalize-tables.mjs
@@ -0,0 +1,23 @@
+/**
+ * Normalize tables to have a newline before and after the content of each cell.
+ *
+ * This is necessary to ensure that the content of each cell is properly formatted by `htmlTable` formatting option
+ * from typedoc-plugin-markdown is used.
+ */
+export default function () {
+  const compiler = this.compiler || this.Compiler;
+  this.compiler = (tree) => {
+    let content = compiler(tree);
+    content = content
+      .replace(/^\s*(<\/?(table|tr|th|td)>)/gm, (match, p1) => p1)
+      .replace(
+        /<td>\s*([\s\S]*?)\s*<\/td>/gm,
+        (match, p1) =>
+          `<td>\n\n${p1
+            .split('\n')
+            .map((line) => line.trim())
+            .join('\n')}\n\n</td>`,
+      );
+    return content;
+  };
+}
diff --git a/packages/typedoc-plugin-remark/src/options/types.ts b/packages/typedoc-plugin-remark/src/options/types.ts
@@ -1,12 +1,14 @@
-/**
- * Describes the options declared by the plugin.
- *
+/*
  * @privateRemarks
  *
  * THIS FILE IS AUTO GENERATED FROM THE OPTIONS CONFIG. DO NOT EDIT DIRECTLY
  *
  * @module
  */
+
+/**
+ * Describes the options declared by the plugin.
+ */
 export interface PluginOptions {
   /**
    * An array of remark plugin names.

diff --git a/packages/typedoc-plugin-remark/src/remark.cjs b/packages/typedoc-plugin-remark/src/remark.cjs
@@ -1,6 +1,6 @@
 /**
  * Parses contents with Remark
- * - The remark eco-system is esm only, therefore we have to import its modules syncronously.
+ * - The remark eco-system is esm only, therefore we have to import its modules synchronously.
  * - In addition we don't want Typescript to transpile this file.
  */
 module.exports = {
@@ -17,6 +17,7 @@ module.exports = {
       ['remark-frontmatter', ['yaml']],
       'remark-gfm',
       'remark-mdx',
+      './normalize-tables.mjs',
       ...userPlugins,
     ];
     const promises = plugins.map(async (plugin) => {
@@ -37,6 +38,7 @@ module.exports = {
     pluginRefs.forEach((pluginRef) => {
       processor.use(pluginRef.pluginFn, pluginRef.options);
     });
+
     await processor.process(file);
 
     writeSync(file);

diff --git a/packages/typedoc-plugin-remark/test/specs/__snapshots__/remark.spec.ts.snap b/packages/typedoc-plugin-remark/test/specs/__snapshots__/remark.spec.ts.snap
@@ -24,9 +24,34 @@ exports[`Remark should parse globals page 1`] = `
 
 #### Parameters
 
-| Parameter | Type     |
-| --------- | -------- |
-| \`param\`   | \`string\` |
+<table>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>
+
+\`param\`
+
+</td>
+<td>
+
+\`string\`
+
+</td>
+<td>
+
+Default text content for \`@category\` tag.
+
+\`\`\`ts
+const x = 1;
+\`\`\`
+
+</td>
+</tr>
+</table>
 
 #### Returns
 
@@ -51,9 +76,34 @@ exports[`Remark should parse globals page without toc 1`] = `
 
 #### Parameters
 
-| Parameter | Type     |
-| --------- | -------- |
-| \`param\`   | \`string\` |
+<table>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>
+
+\`param\`
+
+</td>
+<td>
+
+\`string\`
+
+</td>
+<td>
+
+Default text content for \`@category\` tag.
+
+\`\`\`ts
+const x = 1;
+\`\`\`
+
+</td>
+</tr>
+</table>
 
 #### Returns
 
@@ -80,9 +130,18 @@ title: 'test'
 
 ## Type Parameters
 
-| Type Parameter |
-| -------------- |
-| \`T\`            |
+<table>
+<tr>
+<th>Type Parameter</th>
+</tr>
+<tr>
+<td>
+
+\`T\`
+
+</td>
+</tr>
+</table>
 
 ## Constructors
 
@@ -202,10 +261,18 @@ javascript
 + list item 1
 
 #### Type Parameters
+<table>
+<tr>
+<th>Type Parameter</th>
+</tr>
+<tr>
+<td>
 
-| Type Parameter |
-| -------------- |
-| \`T\`            |
+\`T\`
+
+</td>
+</tr>
+</table>
 
 #### Constructors
 
@@ -228,10 +295,18 @@ javascript
 ### SomeInterface\\<T>
 
 #### Type Parameters
+<table>
+<tr>
+<th>Type Parameter</th>
+</tr>
+<tr>
+<td>
+
+\`T\`
 
-| Type Parameter |
-| -------------- |
-| \`T\`            |
+</td>
+</tr>
+</table>
 
 #### Properties
 
@@ -260,10 +335,24 @@ javascript
 > **some\\_function**(\`param\`): \`void\`
 
 #### Parameters
+<table>
+<tr>
+<th>Parameter</th>
+<th>Type</th>
+</tr>
+<tr>
+<td>
+
+\`param\`
+
+</td>
+<td>
+
+\`string\` | \`boolean\`
 
-| Parameter | Type                  |
-| --------- | --------------------- |
-| \`param\`   | \`string\` \\| \`boolean\` |
+</td>
+</tr>
+</table>
 
 #### Returns
 

diff --git a/packages/typedoc-plugin-remark/test/stubs/module-2.ts b/packages/typedoc-plugin-remark/test/stubs/module-2.ts
@@ -1,2 +1,12 @@
 export const someVariable = true;
+
+/**
+ * @param param
+ *
+ * Default text content for `@category` tag.
+ *
+ * ```ts
+ * const x = 1;
+ * ```
+ */
 export function some_function(param: string) {}
diff --git a/packages/typedoc-plugin-remark/test/typedoc.base.json b/packages/typedoc-plugin-remark/test/typedoc.base.json
@@ -8,7 +8,7 @@
     "./frontmatter-plugin.cjs"
   ],
   "readme": "none",
-  "parametersFormat": "table",
+  "parametersFormat": "htmlTable",
   "disableSources": true,
   "cleanOutputDir": true,
   "hidePageHeader": true,