Support hybrid output file format

[NSeydoux]

What package is the feature request related to?

typedoc-plugin-markdown

Background

Up until v4 of the typedoc-plugin-markdown, it was possible to have the entry document be in a different file format that the rest of the output. Specifically, in my case, we have a manually written restructured text (.rst) index file, and then generated all the API docs in markdown pointing back to that index.rst. We then consumed the whole in a follow-up step to add our own navigation, among other things.

This behavior is no longer possible in v4, where all the generated files must be of the same format. The legacy entryDocument configuration, which allowed to have a file name and its extension, is no longer supported, so the global fileExtension is applied to the entryFileName as well as all the other generated files, which breaks our workflow.

Proposed solution

An additional configuration option, entryFileExtension, could override the default fileExtension, allowing to have a custom index file as we do. Would that be an acceptable addition to the configuration API to maintain previous capabilities?

[tgreyuk]

Sure we could accommodate that.

Could potentially just make the option clever enough to use whatever extension is written to the option ie:

• entryFileName: "index.rst"(use .rst).
• entryFileName: "index (use default ext).

Just to confirm entryFileName also effects all module index pages (but this might not be relevant to your use-case?

[NSeydoux]

Oh I see, I didn't realize the entry point applied to all module indexes, thanks for calling it out. Let me check if that would work with our pipeline with my team, I'll come back to you on that.

If that works, then your proposal would work fine, although I'm always wary of trying to make a configuration option "clever", because it tends to create edge cases. For instance, wouldn't it be a legitimate use case to have to have the entry point files named something like api.index, expecting that the general .md would be added on top of that? Because then either there is a list of "supported" output file extensions, and that becomes a burden for the library, or any /(*)\.(*)/ pattern is supported, with $1 the file name and $2 the extension, but then it might confuse some users who were relying on the previous behavior. If that is a concern, introducing an additional "dumb" config option enforces that this is a purely additive change, entirely opt-in.

And if that doesn't work out of the box and requires some work to be supported, then we might as well do the work to accommodate for the current behavior, and therefore no change would be required on you end.

I'll come back to you when I have a more precise idea of the next steps, and thanks for being so responsive!

[tgreyuk]

FYI have added an example of how to achieve this output with a local plugin. https://github.com/typedoc2md/typedoc-plugin-markdown-scratchpad/tree/main/issues/624.