Question: Can I use "docusaurus-plugin-typedoc" alone with docusaurus app?
Closed this issue · 4 comments
What package is your question related to?
docusaurus-plugin-typedoc
What would you like to ask?
Since I have two repos, for example A and B.
The typescript source code is inside A, and also I generated "typedoc" markdown documents in A.
Then I manually (actually use github actions) copy the generated markdown docs to B, and B is the docusaurus doc app, and I want to only use "docusaurus-plugin-typedoc" alone with docusaurus.
Is it possible?
In the plugin's document: https://typedoc-plugin-markdown.org/plugins/docusaurus/quick-start, it always recommend to use together with "typedoc-plugin-markdown".
Currently using docusaurus-plugin-typedoc in B will serve no purpose as the md files have already been generated. So you can just run docusaurus in B as normal without any typedoc plugins.
The only thing you are really missing is a generated sidebar for navigation. I could probably make it possible to abstract the sidebar logic to be consumed in a custom plugin in A if that would be useful?
Thank you for considering this possibility!
For now in repo A, the generated markdown docs are split into typescript interfaces/classes/functions/etc. And they are organized well in docusaurus sidebar, because docusaurus has the auto sidebar feature, so I don't think you have to create another plugin for docusaurus sidebar.
For markdown documents with docusaurus, I think the biggest issue is, the styling is quite different from typedoc's html docs.
The typedoc html docs have much more pretty css styles, and much more icons and links. I hope markdown could also looks better.
Maybe you could consider, provide an option to generate 'mdx' files instead of 'md', it will allow user to add more js/css in docusaurus to make it prettier than pure markdown.
For now in repo A, the generated markdown docs are split into typescript interfaces/classes/functions/etc. And they are organized well in docusaurus sidebar, because docusaurus has the auto sidebar feature, so I don't think you have to create another plugin for docusaurus sidebar.
If you are happy then great. You would only need a plugin version of sidebar if you were interested in sort order etc.
For markdown documents with docusaurus, I think the biggest issue is, the styling is quite different from typedoc's html docs. The typedoc html docs have much more pretty css styles, and much more icons and links. I hope markdown could also looks better.
It would be possible to bring in some icons for different symbols and something that's been previously considered. Obviously users a free to implement some custom css if they wish. If somebody had something that works well we could also provide some styles as part of the plugin. Users can also make use of docusaurus markdown features (such as admonitions) directly in the doc comments.
Maybe you could consider, provide an option to generate 'mdx' files instead of 'md', it will allow user to add more js/css in docusaurus to make it prettier than pure markdown.
I am not sure about managing a whole alternative mdx output as this plugin is intentionally designed to produce simple markdown docs and not sure it would be a good idea to veer away from that too much. You could of-course render dynamic React pages fully integrated with the Docusaurus ecosystem which another docusaurus plugin has done docusaurus-plugin-typedoc-api.
You would only need a plugin version of sidebar if you were interested in sort order etc.
Oh, if the sidebar can manages the sort orders, then it is also a great plus if we could use it. I forget that part.