diff --git a/designs/2024-plugins.eslint.org-website/README.md b/designs/2024-plugins.eslint.org-website/README.md new file mode 100644 index 00000000..aedd7f18 --- /dev/null +++ b/designs/2024-plugins.eslint.org-website/README.md @@ -0,0 +1,182 @@ +- Repo: [`eslint/json`](https://github.com/eslint/json), [`eslint/markdown`](https://github.com/eslint/markdown) +- Start Date: 2024-08-29 (TBU) +- RFC PR: https://github.com/eslint/rfcs/pull/123 +- Authors: Francesco Trotta + +# plugins.eslint.org Website + +## Summary + + + +This is a proposal to create a plugins.eslint.org website to host documentation for plugins maintained by the ESLint team: currently [`eslint/json`](https://github.com/eslint/json) and [`eslint/markdown`](https://github.com/eslint/markdown). + +## Motivation + + + +In the [2024-08-22 TSC meeting](https://github.com/eslint/tsc-meetings/blob/main/notes/2024/2024-08-22.md) it was agreed to create a website at the subdomain plugins.eslint.org to host documentation for the plugins [`eslint/json`](https://github.com/eslint/json) and [`eslint/markdown`](https://github.com/eslint/markdown). This will improve discoverability for these plugins. The purpose of this RFC is to discuss the details of the implementation of the new website. + +For the initial implementation, the intent is to start with only a minimal set of necessary features. More stuff will be added later as needed. + +## Detailed Design + + + +_Not much detail yet, see [Open Questions](#open-questions) below._ + +Each plugin contains a `README.md` file whose content should be rendered in the website at a URL to be specified. +`eslint/markdown` also contains several `.md` files in the `docs` directory that should be also rendered in the website. + +Additionally to the static content in the documentation files, it should be possible to include specific autogenerated information on certain pages like the version number of a package or the date of the last release. + +We will also need a main page whose content should be editable in a GitHub repo (as markdown, HTML, or other format). +It is unclear how this will work given that two repos are involved. Some possible solutions: +* One of the repos will contain the source code for the main page. +* An additional repo will be created for the main page and other shared content. + +`eslint` and `eslint.org` use Eleventy to generate web pages from markdown files and other metadata. +The new website could use Eleventy or another similar tool. Popular alternatives are Jekyll (used by [GitHub Pages](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll)), MkDocs and many more. +Any tool will require a specific configuration that will be kept in the repos along with the documentation pages and other assets for website. +The tooling to build the website pages from the source files will be probably the same. +Instead of duplicating those tools between the two repos, it may be easier to keep them in a single repo (_which one?_). + +A TSC member will have to create and configure a new site in Netlify. +This site will serve the domain plugins.eslint.org. +If possible, the site should be linked to both GitHub repos [`eslint/json`](https://github.com/eslint/json) and [`eslint/markdown`](https://github.com/eslint/markdown). +If not, we will need to think about it. +The intent is to be able to update the site to automatically from both repos on a specific trigger. +Ideally, it should be possible to specify the URLs and metadata of the repos to include in a central configuration. + +It may be also necessary to create a new token for Netlify to fetch data from the repos (_I do not know if the current token is automatically enabled to access the new repos or not_). + +**TODO:** +* collect suggestions and elaborate +* add task list + +## Documentation + + + +It would be good to announce the new website on the usual channels when it's ready (ESLint blog, X aka Twitter, Mastodon, Discord). + +`eslint/json` and `eslint/markdown` are mentioned in several places in the ESLint documentation, with links pointing to the GitHub repos of the projects or to the pages of their npm packages. +Those links could be modified so that they point to pages in the new documentation website. +Doing this would add visibility to the website and provide a better user experience. + +## Drawbacks + + + +The ESLint team has limited bandwith, and the new website will require effort for setup and maintainance. + +## Backwards Compatibility Analysis + + + +Not relevant for this proposal. + +## Alternatives + + + +**TODO:** add dismissed suggestions here + +## Open Questions + + + +* How can we coordinate one website across multiple repos? Suggested solutions: + * Create an additional repo to maintain the shared logic and content + * Split the shared logic and content between the two plugin repos +* What changes to the infrastructure (not code changes) will be necessary? For example: + * Configure a new site in Netlify + * Create new GitHub tokens for the website to fetch data from the repos + * Register the site URL on search engines + * … +* What content will be shown on the main page? Some ideas: + * A brief introduction to ESLint language plugins + * Links to plugin-specific documentation + * List of sponsors +* When will the website be updated? Common options would be during a release, when the main branch is updated, or using a manual trigger. +* What is the _minimal_ set of features we should have right from the beginning? E.g. + * List of sponsors + * Version support policy + * Version-specific URLs (i.e. `v6.x`, `head`, `latest`, etc.) + * Deploy previews + * Translations + * Ligth/dark themes + * A dedicated design + * … + +## Help Needed + + + +Any help in defining the details of this change or with the subsequent implementation will be greatly appreciated. + +To find out which topics will need help exactly, we need answer the open questions in this RFC first. + +## Frequently Asked Questions + + + +## Related Discussions + + + +* Tracking issue: eslint/eslint#18824