Proposal: `readme.md` builder with examples links to TS Playground

sindresorhus / type-fest

A collection of essential TypeScript types

Creative Commons Zero v1.0 Universal

14.28k stars 542 forks source link

Proposal: `readme.md` builder with examples links to TS Playground #454

Open skarab42 opened 2 years ago

skarab42 commented 2 years ago

Following the hint made by @fregante in #428, I propose a readme generator for the API part.

@sindresorhus I did a POC and you can see the generated readme there.

To generate the markdown I use the TS compiler so no additional dependencies to get the summaries, tags and examples, the only library that is added is lz-string which is the same one that is used by the TS Playground to generate the share links.

In addition to generating the links for the examples, this would allow us to not worry about adding new types to the readme and always have a version that matches the code.

Upvote & Fund

We're using Polar.sh so you can upvote and help fund this issue.
The funding will be given to active contributors.
Thank you in advance for helping prioritize & fund our backlog.

skarab42 commented 2 years ago

@sindresorhus Any thoughts on this?

sindresorhus commented 2 years ago

I think it's a great idea 👍

I didn't check, but it would be nice if a type could appear in multiple categories if it has multiple categories defined.
You need to ensure that all the types sources use the description from the readme.
source | example should be capitalized
Categories: => Categories
Is it really useful to show the type count in the categories section? Feels like noise to me.
We should remove the Template literal category. It was only there previously because we had to document them as only supporting the new TS version.

tommy-mitchell commented 1 year ago

@sindresorhus https://github.com/tommy-mitchell/type-fest/tree/feat-readme-builder

I've been working on expanding this, converting the scripts to TypeScript and using liquidjs for the readme template. I've also added eslint-formatter-pretty for formatting warnings while generating the readme:

Thoughts? Haven't changed anything with the type categories or added missing examples/summaries, etc.

sindresorhus commented 1 year ago

@tommy-mitchell Looks great 👍

Nitpick: I would make it TS Playground => Playground

sindresorhus commented 1 year ago

The code in the inline examples are missing indentation: