typedoc-plugin-markdown: Broken tables

What package is the bug related to?

typedoc-plugin-markdown

Describe the issue

Related to #615

Issues I notice with table formatting, in version 4.0.2.

Interface members, unexpected line-breaks

export interface Rule {
  // ...

  /**
   * Switch to another lexer function after this match,
   * concatenate it's results and continue from where it stopped.
   */
  push?: Lexer;

  // ...
}
export interface RegexRule extends Rule {
  /**
   * Regular expression to match.
   *
   * - Can't have the global flag.
   *
   * - All regular expressions are used as sticky,
   *   you don't have to specify the sticky flag.
   *
   * - Empty matches are considered as non-matches -
   *   no token will be emitted in that case.
   */
  regex: RegExp;
  /**
   * Replacement string can include patterns,
   * the same as [String.prototype.replace()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_string_as_a_parameter).
   *
   * This will only affect the text property of an output {@link Token}, not it's offset or length.
   *
   * Note: the regex has to be able to match the matched substring when taken out of context
   * in order for replace to work - boundary/neighborhood conditions may prevent this.
   */
  replace?: string;
}
## Properties

| Property | Type | Description | Inherited from |
| :------ | :------ | :------ | :------ |
| `push?` | [`Lexer`](../type-aliases/Lexer.md) | Switch to another lexer function after this match,
 concatenate it's results and continue from where it stopped. | [`Rule`](Rule.md).`push` |
| `regex` | `RegExp` | <p>Regular expression to match.</p>
<ul><li>Can't have the global flag.</li><li></li><li>All regular expressions are used as sticky,</li></ul>  you don't have to specify the sticky flag.
<ul><li>Empty matches are considered as non-matches -</li></ul>  no token will be emitted in that case. | - |
| `replace?` | `string` | <p>Replacement string can include patterns,</p>
<p> the same as [String.prototype.replace()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_string_as_a_parameter).</p><p> This will only affect the text property of an output [Token](../type-aliases/Token.md), not it's offset or length.</p><p> Note: the regex has to be able to match the matched substring when taken out of context</p>
<p> in order for replace to work - boundary/neighborhood conditions may prevent this.</p> | - |
... abbreviated ...

Type alias, unexpected line-break

export type Token = {
  // ...

  /**
   * The length of the matched substring.
   *
   * _(Might be different from the text length in case replace value
   * was used in a {@link RegexRule}.)_
   */
  len: number;

  // ...
}
## Type declaration

| Member | Type | Description |
| :------ | :------ | :------ |
| `len` | `number` | <p>The length of the matched substring.</p><p>_(Might be different from the text length in case replace value</p>
<p> was used in a [RegexRule](../interfaces/RegexRule.md).)_</p> |
... abbreviated ...

Function parameters, unexpected line-break

/**
 * Create a lexer function.
 *
 * @param rules - Non-empty array of lexing rules.
 *
 * Rules are processed in provided order, first match is taken.
 *
 * Rules can have the same name - you can have separate rules
 * for keywords and use the same name "keyword" for example.
 *
 * @param options - Lexer options object.
 */
export function createLexer (
  rules: Rules,
  options?: Options
): Lexer;

### Parameters
| Parameter | Type | Description |
| :------ | :------ | :------ |
| `rules` | [`Rules`](../type-aliases/Rules.md) | <p>Non-empty array of lexing rules.</p><p> Rules are processed in provided order, first match is taken.</p><p> Rules can have the same name - you can have separate rules</p>
<p> for keywords and use the same name "keyword" for example.</p> |
| `options`? | [`Options`](../type-aliases/Options.md) | Lexer options object. |

Index, missing description

/**
 * Lexer function.
 *
 * @param str - A string to tokenize.
 * @param offset - Initial offset. Used when composing lexers.
 */
export type Lexer = (
  str: string,
  offset?: number
) => LexerResult;
## Type Aliases

| Type alias | Description |
| :------ | :------ |
| [Lexer](type-aliases/Lexer.md) | - |
... abbreviated ...

(expected “Lexer function.” in the description column)

Index, unexpected line-break

/**
 * Lexing rule.
 *
 * Base rule looks for exact match by it's name.
 *
 * If the name and the lookup string have to be different
 * then specify `str` property as defined in {@link StringRule}.
 */
export interface Rule {
  // ...
}
| Interface | Description |
| :------ | :------ |
| [Rule](interfaces/Rule.md) | Lexing rule.
 |
... abbreviated ...

Index, description trimmed at line-break, no full paragraph, no ellipsis

/**
 * String rule - looks for exact string match that
 * can be different from the name of the rule.
 */
export interface StringRule extends Rule {
  // ...
}
| Interface | Description |
| :------ | :------ |
| [StringRule](interfaces/StringRule.md) | String rule - looks for exact string match that
 |
... abbreviated ...

(expected “String rule - looks for exact string match that can be different from the name of the rule.” in the description column) (there is an unexpected line-break instead)

TypeDoc configuration

{
  "$schema": "https://typedoc.org/schema.json",
  "disableSources": true,
  "entryFileName": "index.md",
  "entryPoints": [ "src/code.ts" ],
  "githubPages": false,
  "hideBreadcrumbs": true,
  "includeVersion": true,
  "readme": "none",
  "out": "docs",
  "plugin": ["typedoc-plugin-markdown"],
  "outputFileStrategy": "members",
  "useCodeBlocks": true,
  "expandParameters": true,
  "parametersFormat": "table",
  "propertiesFormat": "table",
  "typeDeclarationFormat": "table",
  "indexFormat": "table",
}

Expected behavior

No response

About this issue

  • Original URL
  • State: closed
  • Created 3 years ago
  • Comments: 23 (12 by maintainers)

Commits related to this issue

Most upvoted comments

thank you. I think for now (and for simplicity):

  • “table” - will display the first paragraph of the summary in a markdown table (with the windows bug fixed).
  • “htmlTable” - will display the full markdown content in an html table.

Any other configurations i’ll wait to see if there is any community feedback / requests.

I love this idea! It will help keeping everything readable as well.

One note though: with format="table", beware of repeating #331 - I see an extra space in the example above.