[ ] An FAQ based on any GitHub issue questions that come in
[ ] Etc., as discovered
Public API
ts-markdown now has copious amounts of JSDoc comments using fairly standard structure.
As a ts-markdown user and maintainer, I would like to have documentation generated from the JSDoc comments, in addition to any other custom markdown documentation, together in a cohesive set of web pages, which can be linked from the main github readme. I intend for this documentation to be viewable either from the repo Wiki or via GitHub Pages, whichever makes more sense after some analysis.
So far, I've looked at TypeDoc, which seems to get the job done really well when it comes to generating structured documentation. However, I still do not know how to include arbitrary additional content so that I can also provide some cookbook-like content for people who like to learn by example.
Cookbook ideas
To start, I'm envisioning a cookbook with
some common markdown document rendering examples
some simple extensibility examples
some complex extensibility examples
some techniques for leveraging TypeScript to make it easier to code up markdown entries
It sounds like some swaths of the README could be pulled into this cookbook and linked from the README. We'd still need to keep core story of this library out there in plain markdown, even if it is duplicated over in the cookbook.
FAQ
I will likely begin an FAQ based on similar libraries and issues people have come across. This will mainly provide the scaffolding for future use. I know it's something I want to provide eventually, so I'm getting the requirement out here.
kgar
commented
2 years ago
ts-markdown needs documentation
Public API
ts-markdown now has copious amounts of JSDoc comments using fairly standard structure.
As a ts-markdown user and maintainer, I would like to have documentation generated from the JSDoc comments, in addition to any other custom markdown documentation, together in a cohesive set of web pages, which can be linked from the main github readme. I intend for this documentation to be viewable either from the repo Wiki or via GitHub Pages, whichever makes more sense after some analysis.
So far, I've looked at TypeDoc, which seems to get the job done really well when it comes to generating structured documentation. However, I still do not know how to include arbitrary additional content so that I can also provide some cookbook-like content for people who like to learn by example.
Cookbook ideas
To start, I'm envisioning a cookbook with
It sounds like some swaths of the README could be pulled into this cookbook and linked from the README. We'd still need to keep core story of this library out there in plain markdown, even if it is duplicated over in the cookbook.
FAQ
I will likely begin an FAQ based on similar libraries and issues people have come across. This will mainly provide the scaffolding for future use. I know it's something I want to provide eventually, so I'm getting the requirement out here.