From e14bc4fea95d376a7b05851e57442433c339a6d8 Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Thu, 29 Aug 2024 06:53:59 +0200 Subject: [PATCH 1/3] docs: plugins.eslint.org Website --- .../2024-plugins.eslint.org-website/README.md | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 designs/2024-plugins.eslint.org-website/README.md 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..b12b73a5 --- /dev/null +++ b/designs/2024-plugins.eslint.org-website/README.md @@ -0,0 +1,165 @@ +- Repo: [`eslint/json`](https://github.com/eslint/json), [`eslint/markdown`](https://github.com/eslint/markdown) +- Start Date: 2024-08-29 (TBU) +- RFC PR: +- 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. + +`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. +Any tool will require a specific configuration that will be kept in the repos along with the documentation pages and other assets for website. + +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. + +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). + +## 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? +* 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 + * … +* What content will be shown on the main page? +* 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. + +## Frequently Asked Questions + + + +## Related Discussions + + + +* Tracking issue: eslint/eslint#18824 From 769cdaee495a49977ab5f1f75785cf6f0c1b2b5d Mon Sep 17 00:00:00 2001 From: Francesco Trotta Date: Thu, 5 Sep 2024 21:12:08 +0200 Subject: [PATCH 2/3] update --- designs/2024-plugins.eslint.org-website/README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/designs/2024-plugins.eslint.org-website/README.md b/designs/2024-plugins.eslint.org-website/README.md index b12b73a5..ec7aab82 100644 --- a/designs/2024-plugins.eslint.org-website/README.md +++ b/designs/2024-plugins.eslint.org-website/README.md @@ -1,6 +1,6 @@ - Repo: [`eslint/json`](https://github.com/eslint/json), [`eslint/markdown`](https://github.com/eslint/markdown) - Start Date: 2024-08-29 (TBU) -- RFC PR: +- RFC PR: https://github.com/eslint/rfcs/pull/123 - Authors: Francesco Trotta # plugins.eslint.org Website @@ -44,14 +44,17 @@ It is unclear how this will work given that two repos are involved. `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. 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). +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 @@ -66,6 +69,10 @@ It may be also necessary to create a new token for Netlify to fetch data from th 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 -* How can we coordinate one website across multiple repos? +* 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? +* 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 @@ -151,6 +158,8 @@ Not relevant for this proposal. 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