Searchable & Hosted docs for jose

[rishi-raj-jain]

Hey @panva,

I love jose. I've started using it in all of my launchfa.st boilerplates!

But digging up the relevant part from the docs is tough, as there's no global search available.

I'd love to collaborate and get docs up and running for jose. What do you think?

To start off, here's an outline of steps that I can get started with:

• Use https://starlight.astro.build/getting-started/
• Convert the whole docs folder into the content folder as it'd make the whole thing easily searchable with the help of pagefind
• Apply for Vercel open source project program to cover your hosting expenses

[panva]

Hello @rishi-raj-jain

I'd love to collaborate and get docs up and running for jose. What do you think?

I haven't considered a docs site, mainly because I don't believe they're that good or beneficial for the consumer who's looking to get a job done. That's where the current docs entrypoints (https://github.com/panva/jose#json-web-tokens-jwt) come in. They link to a point in the docs which is a good starting point for a given job to be done. Looking to Sign a JWT, here. Looking to verify one? here.

I am quite happy with the typedoc markdown plugin that achieves what is there in the repo mainly for its linkability and ability to have permalinks since it's in git. I also don't have to maintain it, 💯 top feature.

External doc sites suffer from not being able to keep historical record of what the docs were for a given version, a problem that you inherently don't have with git.

[panva]

FWIW it would be possible to have typedoc spit out a .json file version of the docs which could live in the tagged commit as well for any external tools to use to build their representation of the docs. That would be acceptable.