🚀 Feature: Create a documentation website

[JoshuaKGoldberg]

Feature Request Checklist

• I have pulled the latest main branch of the repository.
• I have searched for related issues and found none that matched my issue.

Overview

Some other ESLint plugins have their own websites:

• https://ota-meshi.github.io/eslint-plugin-astro
• https://ota-meshi.github.io/eslint-plugin-yml
• https://eslint.style
• etc.

IMO these websites are great. They provide more friendly, rich documentation than just .md docs pages on GitHub. And they have better SEO.

Proposal: how about we make one for eslint-plugin-package-json?

Additional Info

I've never actually made an ESLint docs website before, and don't know what the options are. Those three linked sites are all on Vitepress. Vitepress is nice. Are there other common options we should look at?

🗂️

[michaelfaith]

Good idea! I've generally used Docusaurus for simple doc sites. But I haven't really explored Vitepress before. So, I'd be open for that too. Whatever we choose, it would be nice if it supports Markdown as the authoring format like Docusaurus. That would allow us to reuse our existing doc pages and not have to keep two sources of truth.

[michaelfaith]

Briefly looking at Vitepress, it looks like a solid option. I don't know Vue at all, but I'm sure it's easy enough to learn, and it seems like it may not even be needed unless we wanted to make additional customizations (beyond the baked in theming). So, I'd be down for giving that a shot. For either option, we'd need to define a theme (including color palette, font, etc) https://vitepress.dev/guide/extending-default-theme. @JoshuaKGoldberg do you have any preferences around that?

[michaelfaith]

Here's a list of some official and community built themes https://github.com/logicspark/awesome-vitepress-v1?tab=readme-ov-file#official-themes

[michaelfaith]

Another data point: https://eslint-react.xyz/ uses Next.js (which I, personally, think is overkill for our use-case, but I like their site...)

[michaelfaith]

Jest's site is built on Docusaurus https://jestjs.io/

[michaelfaith]

Pnpm's site is built on Docusaurus https://pnpm.io/

[michaelfaith]

I'm kinda leaning more towards Docusaurus now 😅

[JoshuaKGoldberg]

we'd need to define a theme (including color palette, font, etc)

I'm not against it! As long as it's fairly straightforward customizations, it would be nice to have a bit of a visual identity. But I think we're probably fine to ship without at first.

Docusaurus

I used to be a big Docusaurus fan, but have recently been very much leaning towards Astro Starlight for similar use cases. Do you have opinions on that?

---

I was also hoping there would be an "ESLint plugin starter" kind of template/theme/plugin/something for one or more of these docs sites...

[michaelfaith]

Hmm, yeah, I hadn't heard of Starlight, but it does seem like a compelling option. It seems a straightforward as the other, and has some nice built-in themes, and runs on vite (+). I'd support that 👍

[michaelfaith]

@JoshuaKGoldberg what about domain and hosting? Thoughts on that side of things?

[JoshuaKGoldberg]

I also wish there was a good free standard for this we could go for... I've been using Vercel for my personal projects because of the great preview PR support. Maybe we can just go with the *.vercel.app domain to start, then look into getting a domain later if it goes well?