Discussions
API reference of an TypeScript library
What's the recommended way of documenting a TypeScript library in readme?
I have a library written in TypeScript and I would like to publish an API reference for it, something like the one for reactjs: https://react.dev/reference/react.
Up to now, my API reference is generated with typedoc, exported to HTML files and exposed as a web page to the public.
Our company policy is to use readme for all documentation related tasks. I tried to exported the API reference to markdown using typedoc plugin and importing it into readme, but the layout doesn't look great and is not readable at all.
Hi Pawel,
For non-REST API documentation, I'd generally recommend build tools that can export to Markdown, which in turn is synced to ReadMe using the ReadMe API or rdme
: https://docs.readme.com/main/docs/rdme
We have customers that use this plugin (if you haven't already tried it): https://www.npmjs.com/package/typedoc-plugin-markdown
Mind sharing an example ReadMe docs page with the TypeDoc output?
-Kanad
Hi Kanad,
thanks for the replay. I ended up using typedoc-plugin-markdown, but I had to write a script to add/modify frontmatter tags. I'm using -next.4 version of typedoc-plugin-markdown to initialize frontmatter tags, but the result is still for from ideal:
- I couldn't find a way to add parentDocSlug tags, so all docs were at the same level in readme after importing - I ended up adding the tag in my custom script
- I couldn't find a way to generate unique slugs - my custom script does it now with slugify library
- I couldn't find a way to define the order of pages - my custom script adds 'order' tag now
Having a plugin to typedoc with would generate something that can be directly imported into readme would be a huge improvement.
I appreciate your response. Typedoc-plugin-markdown was the one I wound up choosing, however I had to whip up a script to handle the frontmatter tags. I've been making use of -next.The frontmatter tags were initialized using the version 4.0.0 of the typedoc-plugin-markdown, however this is far from optimal.
After importing, all of my documents ended up in the same level in readme, and I had to manually add the parentDocSlug tag myself.
I couldn't find a way to generate unique slugs, so I wrote a script that uses the slugify library to do it automatically. 8 ball pool