Should useCodeBlocks output valid TypeScript?

[lukekarrys]

What package is your question related to?

typedoc-plugin-markdown

What would you like to ask?

I have a project that is using prettier to format all the markdown generated by typedoc-plugin-markdown. (Not sure if this is relevant but it is using remarkPlugins: ['unified-prettier'] currently but I also tested with the formatWithPrettier option which I plan to migrate to.)

The reason for my question is that I was searching issues and found this comment #580 (comment) indicating that at least for functions useCodeBlocks: true will change the output so it is valid TypeScript that prettier can then format.

Question

Is the ability to format a declaration or signature a goal for the output of typedoc-plugin-markdown when useCodeBlocks is turned on?

Example

Currently this plugin does a good job at formatting for readability by inserting newlines when useCodeBlocks is turned on. I have a (edge?) case that doesn't get formatted to multiple lines and it would be nice to rely on prettier for this behavior.

This specific case could be fixed by inserting newlines, but I'm more interested in whether I can leverage the rest of the features prettier has, which only work if the output is valid TypeScript.

TypeScript source

export type DepID =
  | `${'' | 'git'}${Delimiter}${string}${Delimiter}${string}${Delimiter}${string}`
  | `${'' | 'git'}${Delimiter}${string}${Delimiter}${string}`
  | `${'file' | 'remote' | 'workspace'}${Delimiter}${string}${Delimiter}${string}`
  | `${'file' | 'remote' | 'workspace'}${Delimiter}${string}`

export type DepIDTuple =
  | [type: 'git', string, string, string]
  | [type: 'registry', string, string, string]
  | [type: 'file', string, string]
  | [type: 'remote', string, string]
  | [type: 'workspace', string, string]

Markdown Output

Here's a playground link which can be edited to replace : with = and then format the code blocks.

### DepID

```ts
type DepID: `${"" | "git"}${Delimiter}${string}${Delimiter}${string}${Delimiter}${string}` | `${"" | "git"}${Delimiter}${string}${Delimiter}${string}` | `${"file" | "remote" | "workspace"}${Delimiter}${string}${Delimiter}${string}` | `${"file" | "remote" | "workspace"}${Delimiter}${string}`;
```

### DepIDTuple

```ts
type DepIDTuple:
  | ["git", string, string, string]
  | ["registry", string, string, string]
  | ["file", string, string]
  | ["remote", string, string]
  | ["workspace", string, string];
```

[tgreyuk]

@lukekarrys thanks.

[email protected] will now render type aliases inside code blocks correctly with =.

: is only valid for type annotations for variables and function signatures etc.

[lukekarrys]

Thanks for the quick fix @tgreyuk! I deployed my site with v4.3.3 and it works great.

Going a bit deeper on my overall question, there are obviously some rendered code blocks that cannot be made into valid TypeScript. For example:

optional type: EdgeLike["type"];

Maybe I'll write a Prettier parser that can figure out what to do in those cases (and use the typedoc-plugin-markdown snapshots as a test suite 😂). That would be a lot of work to make semicolons and double vs single quotes configurable, but I've never known a rabbit hole too deep.

Thanks again! I'll close this as my question has been answered.