feat(core): table updates

.changeset/yellow-beds-smile.md

@@ -0,0 +1,6 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Remove superfluous quotes from prop names (#619)
+- Fix display of index descriptions in tables (#618)

devtools/examples/docusaurus/docusaurus.config.js

@@ -64,6 +64,7 @@ const config = {
         readme: 'none',
         sidebar: { pretty: true },
         outputFileStrategy: 'members',
+        propertiesFormat: 'htmlTable',
         cleanOutputDir: true,
         projectDocuments: [
           '../../../packages/typedoc-plugin-markdown/test/fixtures/DOCUMENT_1.md',

devtools/packages/prebuild-options/tasks/generate-docs.ts

@@ -135,6 +135,7 @@ ${presetsJson}
           meta.push(type);
         }
         if (
+          option.type !== ParameterType.Flags &&
           option.type !== ParameterType.Array &&
           option.type !== ParameterType.Mixed
         ) {

docs/pages/docs/options.mdx

@@ -395,7 +395,7 @@ This option should be set when a full type representation is preferred.
   Specify the render style of parameter and type parameter groups.
 </Callout>
 
-> Accepts either `"list"` or `"table"`. Defaults to `"list"`.
+> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`.
 
 This option either renders parameters for functions and class methods as a list or in tabular format.
 
@@ -413,7 +413,7 @@ This option either renders parameters for functions and class methods as a list
   Specify the render style of property groups for interfaces and classes.
 </Callout>
 
-> Accepts either `"list"` or `"table"`. Defaults to `"list"`.
+> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`.
 
 This option either renders properties for classes and interfaces as a list or in tabular format.
 
@@ -429,7 +429,7 @@ This option either renders properties for classes and interfaces as a list or in
 
 <Callout emoji="💡">Specify the render style of enumeration members.</Callout>
 
-> Accepts either `"list"` or `"table"`. Defaults to `"list"`.
+> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`.
 
 This option either renders members of enums as a list or in tabular format.
 
@@ -447,7 +447,7 @@ This option either renders members of enums as a list or in tabular format.
   Specify the render style for type declaration members.
 </Callout>
 
-> Accepts either `"list"` or `"table"`. Defaults to `"list"`.
+> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`.
 
 This option either renders type declarations as a list or in tabular format.
 
@@ -463,7 +463,7 @@ This option either renders type declarations as a list or in tabular format.
 
 <Callout emoji="💡">Specify the render format for index items.</Callout>
 
-> Accepts either `"list"` or `"table"`. Defaults to `"list"`.
+> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`.
 
 This option renders index items either as a simple list or in a table with a description column exposing the comment summary.
 
@@ -477,6 +477,33 @@ For a packages index page (when `--entryPointStrategy` equals `packages`), the p
 
 ---
 
+### tableColumns
+
+<Callout emoji="💡">
+  Control header alignment and column visibility in tables.
+</Callout>
+
+>
+
+By default, all available data for symbols are displayed in columns, which can result in very large tables.
+
+This option allows you to control the visibility of columns, prioritizing readability over displaying complete data.
+
+```json filename="typedoc.json"
+{
+  "tableColumns": {
+    "excludeDefaultsCol": false,
+    "excludeInheritedFromCol": false,
+    "excludeModifiersCol": false,
+    "excludeOverridesCol": false,
+    "excludeSourcesCol": false,
+    "leftAlignHeadings": false
+  }
+}
+```
+
+---
+
 ### textContentMappings
 
 <Callout emoji="💡">
@@ -626,7 +653,7 @@ This option can be used for engines that require the preservation of anchor link
   Configures how the navigation model will be generated.
 </Callout>
 
-> Defaults to `{"excludeGroups":false,"excludeCategories":false,"excludeFolders":false}`.
+>
 
 By default navigation is not written to file but can be consumed programmatically. Please see [Navigation Guide](/docs/navigation) for more information.
 

packages/typedoc-plugin-markdown/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 4.0.2 (2024-05-15)
+
+### Patch Changes
+
+- Fix symbol url anchors when "flattenOutputFiles" is "true" ([#616](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/616))
+- Normalize line breaks and tags within table columns ([#615](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/615))
+- Remove superfluous spaces and symbol on external links ([#614](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/614))
+- Escape all angle brackets with "santizeComments" ([#612](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/612))
+- Correctly handle quoted symbol names ([#611](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/611))
+- Correctly handle excludeScopesInPaths in windows ([#610](https://github.com/typedoc2md/typedoc-plugin-markdown/issues/610))
+
 ## 4.0.1 (2024-05-07)
 
 ### Patch Changes

packages/typedoc-plugin-markdown/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedoc-plugin-markdown",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "description": "A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.",
   "main": "dist/index.js",
   "files": [

packages/typedoc-plugin-markdown/src/libs/markdown/html-table.ts

@@ -0,0 +1,26 @@
+export function htmlTable(
+  headers: string[],
+  rows: string[][],
+  leftAlignHeadings = false,
+) {
+  return `<table>
+<tr>${headers.map((header) => `<th${leftAlignHeadings ? ' align="left"' : ''}>${header}</th>`).join('')}</tr>${rows
+    .map(
+      (row) =>
+        `
+<tr>${row
+          .map(
+            (cell) =>
+              `
+<td>
+
+${cell === '-' ? '&hyphen;' : cell}
+
+</td>`,
+          )
+          .join('')}
+</tr>`,
+    )
+    .join('')}
+</table>`;
+}

packages/typedoc-plugin-markdown/src/libs/markdown/index.ts

@@ -10,6 +10,7 @@ export { bold } from './bold';
 export { codeBlock } from './code-block';
 export { heading } from './heading';
 export { horizontalRule } from './horizontal-rule';
+export { htmlTable } from './html-table';
 export { indentBlock } from './indent-block';
 export { italic } from './italic';
 export { link } from './link';

packages/typedoc-plugin-markdown/src/libs/markdown/table.ts

@@ -1,10 +1,17 @@
+import { formatTableCell } from '../utils/format-table-cell';
 /**
  * Comments for table
  * @param headers
  * @param rows
  */
-export function table(headers: string[], rows: string[][]) {
+export function table(
+  headers: string[],
+  rows: string[][],
+  headerLeftAlign = false,
+) {
   return `\n| ${headers.join(' | ')} |\n| ${headers
-    .map(() => ':------')
-    .join(' | ')} |\n${rows.map((row) => `| ${row.join(' | ')} |\n`).join('')}`;
+    .map(() => `${headerLeftAlign ? ':' : ''}------`)
+    .join(
+      ' | ',
+    )} |\n${rows.map((row) => `| ${row.map((cell) => formatTableCell(cell)).join(' | ')} |\n`).join('')}`;
 }

packages/typedoc-plugin-markdown/src/libs/utils/format-table-cell.spec.ts

@@ -0,0 +1,16 @@
+import { formatTableCell } from './format-table-cell';
+
+describe('formatTableCell', () => {
+  it('should correctly format the cell content', () => {
+    const input = `
+      This is a test
+      \`\`\`ts
+      const x = 10;
+      \`\`\`
+      with multiple   spaces.
+    `;
+    const expectedOutput =
+      'This is a test `const x = 10;` with multiple spaces.';
+    expect(formatTableCell(input)).toBe(expectedOutput);
+  });
+});

packages/typedoc-plugin-markdown/src/libs/utils/format-table-cell.ts

@@ -0,0 +1,15 @@
+/**
+ * - Replace new lines with spaces
+ * - Replaces code blocks with single backticks
+ * - Replaces multiple spaces with single spaces
+ */
+export function formatTableCell(str: string) {
+  return str
+    .replace(/\n/g, ' ')
+    .replace(
+      /```(\w+\s)?([\s\S]*?)```/gs,
+      (match, p1, p2) => `\`${p2.trim()}\``,
+    )
+    .replace(/ +/g, ' ')
+    .trim();
+}

packages/typedoc-plugin-markdown/src/libs/utils/index.ts

@@ -3,9 +3,10 @@
 export { camelToTitleCase } from './camel-to-title-case';
 export { escapeChars } from './escape-chars';
 export { formatMarkdown } from './format-markdown';
-export { formatTableColumn } from './format-table-column';
+export { formatTableCell } from './format-table-cell';
 export { getFileNameWithExtension } from './get-file-name-with-extension';
 export { isQuoted } from './is-quoted';
+export { normalizeLineBreaks } from './normalize-line-breaks';
 export { removeFirstScopedDirectory } from './remove-first-scoped-directory';
 export { removeLineBreaks } from './remove-line-breaks';
 export { sanitizeComments } from './sanitize-comments';

packages/typedoc-plugin-markdown/src/libs/utils/normalize-line-breaks.spec.ts

@@ -0,0 +1,24 @@
+import { normalizeLineBreaks } from './normalize-line-breaks';
+
+describe('normalizeLineBreaks', () => {
+  it('should correctly concatenate lines', () => {
+    const input = `This line should be concatenated with the next one.
+The next line.
+
+This is the next line double break.
+- list item 1
+- list item 2
+
+This is another test.`;
+
+    const expectedOutput = `This line should be concatenated with the next one. The next line.
+
+This is the next line double break.
+- list item 1
+- list item 2
+
+This is another test.`;
+
+    expect(normalizeLineBreaks(input)).toBe(expectedOutput);
+  });
+});

packages/typedoc-plugin-markdown/src/libs/utils/normalize-line-breaks.ts

@@ -0,0 +1,38 @@
+export function normalizeLineBreaks(str: string): string {
+  const codeBlocks: string[] = [];
+
+  const placeholder = '\n___CODEBLOCKPLACEHOLDER___\n';
+  str = str.replace(/```[\s\S]*?```/g, (match) => {
+    codeBlocks.push(match);
+    return placeholder;
+  });
+
+  const lines = str.split('\n');
+  let result = '';
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].length === 0) {
+      result = result + lines[i] + '\n';
+    } else {
+      if (
+        !lines[i].startsWith('#') &&
+        lines[i + 1] &&
+        /^[a-zA-Z`]/.test(lines[i + 1])
+      ) {
+        result = result + lines[i] + ' ';
+      } else {
+        if (i < lines.length - 1) {
+          result = result + lines[i] + '\n';
+        } else {
+          result = result + lines[i];
+        }
+      }
+    }
+  }
+
+  result = result.replace(
+    new RegExp(placeholder, 'g'),
+    () => `${codeBlocks.shift()}` || '',
+  );
+
+  return result;
+}

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

@@ -390,6 +390,26 @@ export const indexFormat: Partial<DeclarationOption> = {
   defaultValue: FormatStyle.List,
 };
 
+/**
+ * By default, all available data for symbols are displayed in columns, which can result in very large tables.
+ *
+ * This option allows you to control the visibility of columns, prioritizing readability over displaying complete data.
+ *
+ * @category UX
+ */
+export const tableColumns: Partial<DeclarationOption> = {
+  help: 'Control header alignment and column visibility in tables.',
+  type: ParameterType.Flags,
+  defaults: {
+    excludeDefaultsCol: false,
+    excludeInheritedFromCol: false,
+    excludeModifiersCol: false,
+    excludeOverridesCol: false,
+    excludeSourcesCol: false,
+    leftAlignHeadings: false,
+  },
+};
+
 /**
  * <Callout type="warning">
  * **Please note TypeDoc 0.26 will be introducing a native i18n implementation. This option will likely be deprecated in favour of utilizing the native implementation when 0.26 is released.**