-
-
Notifications
You must be signed in to change notification settings - Fork 70
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: plugins.eslint.org Website #123
Closed
Closed
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My expectation when you agreed to put together the RFC is that you'd come up with an initial design based on your understanding of the problem and we could iterate on it together. It looks like this is still just a list of questions. What do you think about closing this PR until you've had time to come up with a concrete proposal, rather than leaving this open?
I'd much rather have you attempt to answer the open questions and come up with an initial proposal than require all of us to keep going around on open questions to make any progress.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the feedback. I was trying to collect input based on the experience of others who already worked with the eslint.org website and the tools we use there, but I can see that this is just a bit too abstract to engage users in a discussion. I agree it makes sense to close this RFC at this point, and I will try to come up with a design and likely a prototype of how the plugins website will work. Then I will open a new RFC to discussion the suggested changes.