typedoc-plugin-markdown v4

[tgreyuk]

We will be releasing an next version of typedoc-plugin-markdown v4 in the near future - a rebuild of the plugin featuring several improvements:

• Removal of handlebars
• MDX support as standard
• Updated theming model to follow the html theme, (which means the theme can be easily overridden/adapted)
• Updated directory structure to follow the project module structure
• Ability to choose which symbols should be rendered to a single doc, with the ability to add all symbols into single doc.
• Ability to choose between list/table styles.
• UI improvements.

Please use this area to raise feature requests and idea improvements.

[lorenzolewis]

For the list style, I have an implementation for enums specifically (you can see the render here https://tauri.app/v1/api/js/fs#basedirectory). If you aren't working on it already then I could draft up a PR in that direction.

[tgreyuk]

that looks cool - PR would be great.

[suleyman222]

Is there any timeline on when the first version of v4 will be released? The changes look great and I would love to start using it in a project.

[tgreyuk]

In a couple of weeks (hopefully). Just want to make sure all the main items in the description are covered.

[lorenzolewis]

@tgreyuk I'm starting with some low-hanging fruits. In #370 you mentioned the possibility of getting rid of dividers by default. Would you be alright with simply removing the --- here?

https://github.com/tgreyuk/typedoc-plugin-markdown/blob/e86bda396e03731d95956865fc4c9a83967e01ae/packages/typedoc-plugin-markdown/src/support/els.ts#L14

Or do you have some flexibility you'd like to expose somehow to allow overriding it?

[tgreyuk]

I'd rather keep that method as a helper (as it might be useful) and just remove where its being called from the partials. If it works better without the hrs then just leave them out altogether.

[lorenzolewis]

How about just changing it from \n\n--- to \n\n? Or would you like it removed altogether from the partials?

[tgreyuk]

I think just remove it from the partials. I am not even sure that we need an additional option around it. Lets just create something we think works best. If a user wants to add other stuff they can just extend the theme themselves.

[lorenzolewis]

Cool, I'll PR that

[lorenzolewis]

#382

[suleyman222]

Would be nice to see a fix for #252. I don't think there's a straightforward way to customize which characters are escaped currently. Maybe an option that looks something like escapedChars: ['>', '<', `{`, '_', '`', '\', ...] or some way to overwrite it in the context?

[tgreyuk]

Yes will look at this next.

[tgreyuk]

This should be fixed in next version typedoc-plugin-markdown@next . Please let me know .

[suleyman222]

Hey, I finally had a chance to test the next version and take a look at this. Thanks for the great work!

The escaping seems to be working in most cases, but I noticed one case where curly braces aren't escaped when declaring an intersection or union type with an object literal type.

For example:

export type Foo = {
    foo: string;
}

export type Bar = Foo & {
    bar: number;
}

results in:

### Bar

> [`Foo`](README.md#Foo) & {
    `bar`: `number`;
}

where the { isn't escaped and that leads to this error. This doesn't seem to be a problem for regular object literal types, since they're wrapped in code blocks.

[tgreyuk]

Thanks @suleyman222 - i have a fixed this. will let you know when its been deployed with next release.

[lorenzolewis]

Right now you're just running test suites for Output File Strategy:

https://github.com/tgreyuk/typedoc-plugin-markdown/blob/7a920bffb8a68c3a96fa21e6767fc4912694ff84/packages/typedoc-plugin-markdown/package.json#L15

Ideally I'd like to wait until the rest of the suites are enabled and the snapshots are where you'd like them before I start some larger PRs for list styles and the single-line return format (that would look like Returns: Promise<string | null>).

Is there anything I can do to help with this?

[Zamiell]

Posting here to request an update on #328, hopefully this kind of functionality can be in version 4 of the plugin.

[Zamiell]

Thanks Tom. I took a look, and in that repo, you manually specify each file individually in the "entryPoints".

Unfortunately, this does not solve the problem, because it causes me to have to specify every single file in my entire repository inside of my "entryPoints" file, which results in hundreds of entries like this: https://github.com/IsaacScript/isaacscript/blob/main/packages/isaacscript-common/typedoc.json#L13

As I said above, this becomes very hard to maintain, because whenever we need to add a new file to the list of library exports in the "index.ts" file, we often forget to add it to the "typedoc.json" file, causing the documentation to get out of sync / become bugged.

Having to duplicate all of the information in the "index.ts" file a second time in the "typedoc.json" file violates DRY, which is the root cause of these bugs. This is the motivation behind wanting an option like "groupBySourceFile".

[tgreyuk]

Thanks Tom. I took a look, and in that repo, you manually specify each file individually in the "entryPoints".

Well, you could achieve the same thing with:

  "entryPoints": ["./src"],
  "entryPointStrategy": "expand",

[Zamiell]

Tom,

I dont think that is a solution either, because then TypeDoc would document private files that end-users should not have access to, right? I only want to document things that are specified in the "index.ts" file (the thing pointed to by the "main" field in the "package.json" file).

[tgreyuk]

right - well i am running out of ideas/suggestions im afraid. you could of course configure entrypoints by reading the file system with path and fs.

[Zamiell]

configure entrypoints by reading the file system

That is smart; I've not thought of that before.

Looking into this more, yes, it seems like that instead of using "typedoc.json", I could instead use "typedoc.js", and then manually prepare the "entryPoints" array at the top of the file (by parsing the contents of "index.ts" file). So yes, that seems like the best option for now.

However, it would be fantastic if TypeDoc could provide an option for this out of the box (e.g. groupBySourceFile), as arriving at this conclusion / script setup is non-trivial.