fix(core): display all available markdown content for index html tables

typedoc2md · Jul 5, 2024 · b710dc9 · b710dc9
1 parent 5e8b1e6
commit b710dc9
Show file tree

Hide file tree

Showing 9 changed files with 1,042 additions and 183 deletions.
diff --git a/devguide/typedoc-plugin-markdown/options/namespaces/declarations/README.md b/devguide/typedoc-plugin-markdown/options/namespaces/declarations/README.md
@@ -573,7 +573,7 @@ This option renders index items either as a simple unordered list or in a table.
 
 When table style is selected the following will be the behaviour:
 
-* For a **members index**, a description column will be added to the table with the first paragraph of the comment summary.
+* For a **members index**, a description column will be added with key `table` - the first paragraph of the comment summary, or key `htmlTable` - the entire comment contents.
 * For a **packages index**, (when `--entryPointStrategy` equals `packages`), the package.json description will be displayed with an additional "Version" column (when `--includeVersion` equals true).
 * For a **documents index** a description column will be added to the table printing the `"description"` frontmatter variable.
 

diff --git a/docs/pages/docs/options/display-options.mdx b/docs/pages/docs/options/display-options.mdx
@@ -1,4 +1,4 @@
-import { Callout, FileTree } from 'nextra/components';
+import { Callout, FileTree } from "nextra/components";
 
 # Display Options
 
@@ -136,13 +136,13 @@ Use this option to preserve the position of the tag content with the comment sum
 
 <Callout emoji="💡">Sets the format of index items.</Callout>
 
-> Accepts one of `"list"` | `"table"`. Defaults to `"list"`.
+> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`.
 
 This option renders index items either as a simple unordered list or in a table.
 
 When table style is selected the following will be the behaviour:
 
-- For a **members index**, a description column will be added to the table with the first paragraph of the comment summary.
+- For a **members index**, a description column will be added with key `table` - the first paragraph of the comment summary, or key `htmlTable` - the entire comment contents.
 - For a **packages index**, (when `--entryPointStrategy` equals `packages`), the package.json description will be displayed with an additional "Version" column (when `--includeVersion` equals true).
 - For a **documents index** a description column will be added to the table printing the `"description"` frontmatter variable.
 

diff --git a/docs/public/schema.json b/docs/public/schema.json
@@ -21,7 +21,11 @@
         },
         "classPropertiesFormat": {
           "type": "string",
-          "enum": ["list", "table", "htmlTable"],
+          "enum": [
+            "list",
+            "table",
+            "htmlTable"
+          ],
           "description": "[typedoc-plugin-markdown] Sets the format of property groups for classes.",
           "default": "list"
         },
@@ -36,7 +40,11 @@
         },
         "enumMembersFormat": {
           "type": "string",
-          "enum": ["list", "table", "htmlTable"],
+          "enum": [
+            "list",
+            "table",
+            "htmlTable"
+          ],
           "description": "[typedoc-plugin-markdown] Sets the format of enumeration members.",
           "default": "list"
         },
@@ -84,13 +92,21 @@
         },
         "indexFormat": {
           "type": "string",
-          "enum": ["list", "table"],
+          "enum": [
+            "list",
+            "table",
+            "htmlTable"
+          ],
           "description": "[typedoc-plugin-markdown] Sets the format of index items.",
           "default": "list"
         },
         "interfacePropertiesFormat": {
           "type": "string",
-          "enum": ["list", "table", "htmlTable"],
+          "enum": [
+            "list",
+            "table",
+            "htmlTable"
+          ],
           "description": "[typedoc-plugin-markdown] Sets the format of property groups for interfaces.",
           "default": "list"
         },
@@ -143,13 +159,20 @@
         },
         "outputFileStrategy": {
           "type": "string",
-          "enum": ["members", "modules"],
+          "enum": [
+            "members",
+            "modules"
+          ],
           "description": "[typedoc-plugin-markdown] Determines how output files are generated.",
           "default": "members"
         },
         "parametersFormat": {
           "type": "string",
-          "enum": ["list", "table", "htmlTable"],
+          "enum": [
+            "list",
+            "table",
+            "htmlTable"
+          ],
           "description": "[typedoc-plugin-markdown] Sets the format of parameter and type parameter groups.",
           "default": "list"
         },
@@ -159,13 +182,21 @@
         },
         "propertiesFormat": {
           "type": "string",
-          "enum": ["list", "table", "htmlTable"],
+          "enum": [
+            "list",
+            "table",
+            "htmlTable"
+          ],
           "description": "[typedoc-plugin-markdown] Sets the format of property groups for interfaces and classes.",
           "default": "list"
         },
         "propertyMembersFormat": {
           "type": "string",
-          "enum": ["list", "table", "htmlTable"],
+          "enum": [
+            "list",
+            "table",
+            "htmlTable"
+          ],
           "description": "[typedoc-plugin-markdown] Sets the format of style for property members for interfaces and classes.",
           "default": "list"
         },
@@ -247,7 +278,11 @@
         },
         "typeDeclarationFormat": {
           "type": "string",
-          "enum": ["list", "table", "htmlTable"],
+          "enum": [
+            "list",
+            "table",
+            "htmlTable"
+          ],
           "description": "[typedoc-plugin-markdown] Sets the format of style for type declaration members.",
           "default": "list"
         },
@@ -268,4 +303,4 @@
       "definitions": {}
     }
   ]
-}
+}
diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts
@@ -367,7 +367,7 @@ export const blockTagsPreserveOrder: Partial<DeclarationOption> = {
  *
  * When table style is selected the following will be the behaviour:
  *
- * - For a **members index**, a description column will be added to the table with the first paragraph of the comment summary.
+ * - For a **members index**, a description column will be added with key `table` - the first paragraph of the comment summary, or key `htmlTable` - the entire comment contents.
  * - For a **packages index**, (when `--entryPointStrategy` equals `packages`), the package.json description will be displayed with an additional "Version" column (when `--includeVersion` equals true).
  * - For a **documents index** a description column will be added to the table printing the `"description"` frontmatter variable.
  *

diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-reflection.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-description-for-reflection.ts
@@ -11,7 +11,7 @@ export function getDescriptionForReflection(
   if (comment?.summary?.length) {
     return this.helpers
       .getCommentParts(comment.summary)
-      ?.split('\n\n')[0]
+      ?.split(/(\r?\n){2}/)[0]
       .replace(/\r?\n/g, ' ');
   }
   return null;

diff --git a/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-group-index-table.ts b/packages/typedoc-plugin-markdown/src/theme/context/helpers/get-group-index-table.ts
@@ -15,6 +15,8 @@ export function getGroupIndexTable(
     'tableColumnSettings',
   ).leftAlignHeaders;
 
+  const isHtmlTable = this.options.getValue('indexFormat') === 'htmlTable';
+
   const childKindStrings = children.map((child) =>
     ReflectionKind.singularString(child.kind),
   );
@@ -29,16 +31,27 @@ export function getGroupIndexTable(
     if (child.url) {
       row.push(link(escapeChars(child.name), this.getRelativeUrl(child.url)));
     }
-    const description =
-      child instanceof DeclarationReflection
-        ? this.helpers.getDescriptionForReflection(child)
-        : ((child as DocumentReflection).frontmatter.description as string);
-    row.push(description || '-');
+
+    const description = () => {
+      if (child instanceof DocumentReflection) {
+        return child.frontmatter.description as string;
+      }
+      if (!child.comment) {
+        return '';
+      }
+      return isHtmlTable
+        ? this.partials.comment(child.comment, {
+            isTableColumn: true,
+          })
+        : this.helpers.getDescriptionForReflection(child);
+    };
+
+    row.push(description() || '-');
 
     rows.push(row);
   });
 
-  return this.options.getValue('indexFormat') === 'htmlTable'
+  return isHtmlTable
     ? htmlTable(headers, rows, leftAlignHeadings)
     : table(headers, rows, leftAlignHeadings);
 }
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts
@@ -108,6 +108,7 @@ const config: Record<string, Fixture> = {
         navigationModel: {
           excludeGroups: true,
         },
+        indexFormat: 'table',
       },
       {
         readme: 'none',
@@ -120,7 +121,7 @@ const config: Record<string, Fixture> = {
         ],
         hideGroupHeadings: true,
         useHTMLAnchors: true,
-        indexFormat: 'table',
+        indexFormat: 'htmlTable',
         categorizeByGroup: false,
       },
     ],

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/groups/basic.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/groups/basic.ts
@@ -9,6 +9,14 @@
  * and comments on a soft line.
  *
  * Comments on double new line.
+ *
+ * ```typescript
+ * const a = new InterfaceA();
+ * ```
+ *
+ * @remarks
+ *
+ * Block tag content.
  */
 export interface InterfaceA {
   propA: string;