Feature request: Apply replace also to README's included with [[include]]

[Hi-Fi]

Currently plugin seems to be replacing text only in project's README.md, but not ones which are included with include.

[krisztianb]

Hi. I haven't used this feature of TypeDoc before. Could you give an example on how you are using that include tag?

[Hi-Fi]

We have module, that publishes multiple modules as namespaces. Now I'm able to include README for each namespace as those would be modules. So a bit like monorepo, but without real modules.

Index.ts is like

/**
 * [[include:./module-1/README.md]]
 */
export { * as module_1 } from './module-1';

/**
 * [[include:./module-2/README.md]]
 */
export { * as module_2 } from './module-2';

Those READMEs have now both images and other md files linked, that point to wrong place in generate document.

For images things can be solved with media, and for other markdowns with @knodes/typedoc-plugin-pages, but links can't be suitable for those in the original READMEs as then those wouldn't work in repository view.

Hopefully this clarifies.

[Hi-Fi]

Example repo: https://github.com/Hi-Fi/typedoc-plugins-example/tree/external_pages.

Expected replacement in https://github.com/Hi-Fi/typedoc-plugins-example/blob/external_pages/src/module-2/README.md?plain=1 which is referred to be included in https://github.com/Hi-Fi/typedoc-plugins-example/blob/external_pages/src/index.ts#L13.

[krisztianb]

I looked into this and it turns out to be more difficult than I expected.

The markdown files that are included with [include] are parsed and included into the documentation by the renderer of TypeDoc at the end of creating the documentation. There is no way to replace things in those files the same way the plugin does in code comments or the README file.

A possible solution is to subscribe to the MarkdownEvent.PARSE event of the renderer and to do the replacing while the renderer is including the files.

The downer of this solution is that with that event the plugin can only replace things in the already parsed text. So you have to specify your replacement patterns according to how the parsed MD file (which is HTML) will look like and not according to the original MD file that is included.

Would that work for you?

[Hi-Fi]

Hmm... I think it could work, as the paths are quite simple at least in case I tried with demo and the project where I encountered this issue.

[krisztianb]

I was thinking about this a little bit more and I really don't like the idea of replacing in the already parsed markdown content. That is not in line with how the plugin is replacing texts in comments and the README.

I think we are going to have to extend TypeDoc itself to have a nice solution, so I created a corresponding issue here: https://github.com/TypeStrong/typedoc/issues/2083

[krisztianb]

Added in 2.1.0