search

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
705 stars 175 forks source link

[typedoc-plugin-markdown@next] outputFileStrategy is ignored in 'packages' mode. #525

Closed adambergman closed 9 months ago

adambergman commented 9 months ago

When using the packages entry point strategy in typedoc, the plugin is not properly respecting the outputFileStrategy setting in the typedoc configurations in each package. It appears that the plugin ignores the setting in a package's typedoc.json (or js) configuration and uses the option set at the root level only.

In the example repo below (taken from the typedoc documentation), I've added typedoc-plugin-markdown, and set outputFileStrategy to members in the "bar" package's typedoc.json file. Running typedoc with the npm run docs command will output modules style markdown files for all 3 packages, instead of only doing so for "baz" and "foo" and output members style for "bar".

Expected Result: docs/@typedoc/bar - markdown files for members docs/@typedoc/baz - markdown files for modules docs/@typedoc/foo - markdown files for modules

Actual Result: docs/@typedoc/bar - markdown files for modules docs/@typedoc/baz - markdown files for modules docs/@typedoc/foo - markdown files for modules

https://github.com/adambergman/typedoc-plugin-markdown-packages-outputstrategy

tgreyuk commented 9 months ago

Thanks for providing a detailed description and the repo. This issue is resolved in typedoc-plugin-markdown@4.0.0-next.37.

It is worth mentioning that output / theme options are in general not respected in typedoc configs for each package even for the default html theme. This is because (at a very high level) specific package options are resolved temporarily when a project is converted into a project before being passed to the themes, at which point only base options are available.

Anyway let me know if you notice any issues with the fix.

adambergman commented 9 months ago

Thanks @tgreyuk. Works like a charm! I'm always amazed and grateful at how quickly you respond to feedback in this project.

I was worried that having different output strategies might make it difficult to link between packages that use different output strategies but that is working perfectly as well.

For some background on why this is so important for us – we've declared types for a huge third-party JS library. We much prefer the way the modules strategy renders our docs with our static site generator, but this approach with the third party declarations package results in a single 3.3 MB markdown file that crashes the SSG and VSCode's markdown language server 🤦

This is a game changer for us – thanks again!