Improve documentation and create a website

[zeyuri]

Hi

I really love this library and I can get my way around the source to understand things.

But I really think we could improve the documention and include some examples. And maybe create a website.

I would love to contribute with this since I have a lot of experience on writing documentation and websites for it.

Do you think this is a good idea? Would be possible for me to work on this?

[sindresorhus]

I'm happy to improve the documentation, but it would be great to discuss what needs improving before any work is done.

I don't really see the need for a website. Ky is for developers and the GitHub interface works well enough.

[sholladay]

The main benefit of a website that I can see would be to have an easy to use playground. Ideally one that would help people understand CORS.

Much of this could be accomplished with CodeSandbox links, though.

[MimmyJau]

As someone new to the library, my humble suggestion for lowest-hanging fruit would be:

1. More examples (e.g. for ky.get(), json, searchParams, timeout, etc.)
2. Table of contents
3. Related to a Table of Contents, but clearer delineation between sections and subsections (e.g. why is the font for options smaller than ky.delete(input, options?), is it a nested subsection only for that method?)

[sholladay]

I'm interested in starting to build a website in order to improve the learning experience. And to really do that, I think we need interactive examples.

Here's what I'm thinking:

• Create a www folder with some static files
• No build step for now, keep it simple, even if there's some copy paste between a few pages
• Use Cloudflare Pages for hosting it, mostly so we can easily make use of Pages Functions or Workers to respond to Ky requests, and maybe a domain
• Some kind of component or CSS framework that doesn't require a build step - Bulma would be my pick

[RndUsername]

I had great success with starlight. It generates the docs from markdown files and you can extend them with custom components. Here is my real world example.

[sholladay]

Looks like an excellent choice overall and I will give it a try. I especially like that it has built-in search. That said, being a SSG, it does have a build step. And if we are going to use something like that, then I think we should put the site in a separate repo.

I was hoping to avoid that for the time being, at least until we have a good sense of what our true needs are. For example, I want to embed an editor like CodeMirror on the left and a results pane on the right, with some buttons to run and reset the code examples. But some of the more basic markdown docs generators don't have good support for multi-column layouts within the main content. Although, from what I can tell, Starlight should be able to handle that.

Do you have a link to a Starlight site that has anything like that?

[sindresorhus]

I think Starlight would be a good choice.

[sindresorhus]

Starlight is based on Astro, and it's easy to build Astro in GitHub Actions and host it with GitHub Pages.

[Chinoman10]

Better option (IMHO) would be hosting on Cloudflare Pages.

Same ease of deployment and you get additional benefits (100k/day free serverless functions for whatever needs (such as a contact form that sends the content to Discord/Telegram/Slack) and less constraints (unlimited visits/traffic/bandwidth, Cloudflare has a larger web infra & experience dealing with bot nets compared to Microsoft, repo doesn't have to be open-source, among many other benefits).

In any case, I can't suggest Starlight enough, Astro is really next level and the Starlight theme with "batteries included" is really the best possible sensible choice for building documentation websites :)

Would love to see a Ky website (even if it's just docs) <3

[sholladay]

I haven't pushed anything yet but there is a Starlight website in the works. Happy to report that I am now a big fan of Astro and Starlight. 😀

I agree that Cloudflare is better in almost every way. I use them for domains, DNS, Pages, functions, and storage. The UI is simple, the free tier is solid (paid tier tends to be cheaper than AWS, too), and performance is excellent. I keep hoping they'll do an EC2 or Heroku competitor, for long running servers, and a managed Postgres database...

That said, I also understand wanting to keep everything in GitHub, where possible. Too bad GitHub doesn't offer domains and DNS.