docs: plugins.eslint.org Website

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
+
+<!-- One-paragraph explanation of the feature. -->
+
+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
+
+<!-- Why are we doing this? What use cases does it support? What is the expected
+outcome? -->
+
+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
+
+<!--
+   This is the bulk of the RFC.
+
+   Explain the design with enough detail that someone familiar with ESLint
+   can implement it by reading this document. Please get into specifics
+   of your approach, corner cases, and examples of how the change will be
+   used. Be sure to define any new terms in this section.
+-->
+
+_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
+
+<!--
+    How will this RFC be documented? Does it need a formal announcement
+    on the ESLint blog to explain the motivation?
+-->
+
+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
+
+<!--
+    Why should we *not* do this? Consider why adding this into ESLint
+    might not benefit the project or the community. Attempt to think 
+    about any opposing viewpoints that reviewers might bring up. 
+
+    Any change has potential downsides, including increased maintenance
+    burden, incompatibility with other tools, breaking existing user
+    experience, etc. Try to identify as many potential problems with
+    implementing this RFC as possible.
+-->
+
+The ESLint team has limited bandwith, and the new website will require effort for setup and maintainance.
+
+## Backwards Compatibility Analysis
+
+<!--
+    How does this change affect existing ESLint users? Will any behavior
+    change for them? If so, how are you going to minimize the disruption
+    to existing users?
+-->
+
+Not relevant for this proposal.
+
+## Alternatives
+
+<!--
+    What other designs did you consider? Why did you decide against those?
+
+    This section should also include prior art, such as whether similar
+    projects have already implemented a similar feature.
+-->
+
+**TODO:** add dismissed suggestions here
+
+## Open Questions
+
+<!--
+    This section is optional, but is suggested for a first draft.
+
+    What parts of this proposal are you unclear about? What do you
+    need to know before you can finalize this RFC?
+
+    List the questions that you'd like reviewers to focus on. When
+    you've received the answers and updated the design to reflect them, 
+    you can remove this section.
+-->
+
+* 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
+
+<!--
+    This section is optional.
+
+    Are you able to implement this RFC on your own? If not, what kind
+    of help would you need from the team?
+-->
+
+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
+
+<!--
+    This section is optional but suggested.
+
+    Try to anticipate points of clarification that might be needed by
+    the people reviewing this RFC. Include those questions and answers
+    in this section.
+-->
+
+## Related Discussions
+
+<!--
+    This section is optional but suggested.
+
+    If there is an issue, pull request, or other URL that provides useful
+    context for this proposal, please include those links here.
+-->
+
+* Tracking issue: eslint/eslint#18824