typedoc2md / typedoc-plugin-markdown

A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.
https://typedoc-plugin-markdown.org
MIT License
697 stars 173 forks source link

Code blocks after the param list are inlined #454

Closed mamcx closed 1 year ago

mamcx commented 1 year ago

When I add a code block for show how use the API at the end it gets mangled because is inlined:

  /**
   * Creates a new `SpacetimeDBClient` database client and set the initial parameters.
   * 
   * @param host The host of the spacetimeDB server
   * 
   * ```ts
   * const host = "ws://localhost:3000";
   * ```
   * 
  */

Shows as:

### constructor

• **new SpacetimeDBClient**(`host`, `name_or_address`, `auth_token?`, `protocol?`)

Creates a new `SpacetimeDBClient` database client and set the initial parameters.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `host` | `string` | The host of the spacetimeDB server ```ts const host = "ws://localhost:3000"; ``` |
| `name_or_address` | `string` | - |
| `auth_token?` | `string` | - |
| `protocol?` | ``"binary"`` \| ``"json"`` | - |
tgreyuk commented 1 year ago

Code blocks won't render properly inside a table. I think if code blocks are required in param description then we need to introduce an option to display parameters in a list style (rather than a table) - like the HTML theme does.

mamcx commented 1 year ago

Well, the thing is that from the POW of the writer, the code block is not "inside". Why is it not enough to have space between params & code?

tgreyuk commented 1 year ago

Sorry I don't fully understand - do you have an example of desired output?

mamcx commented 1 year ago

Sure:

Creates a new `SpacetimeDBClient` database client and set the initial parameters.

#### Parameters

| Name              | Type                       | Description                                                                                |
| :---------------- | :------------------------- | :----------------------------------------------------------------------------------------- |
| `host`            | `string`                   | The host of the spacetimeDB server                                                         |
| `name_or_address` | `string`                   | The name or address of the spacetimeDB module                                              

```ts
const host = "ws://localhost:3000";
tgreyuk commented 1 year ago

ok - you could use block tags to split up the comments, like:

/** 
   * Creates a new `SpacetimeDBClient` database client and set the initial parameters.
   *
   * @param host The host of the spacetimeDB server
   *
   * @example
   *
   * ```ts
   * const host = "ws://localhost:3000";
   * ```
   */