Skip to content
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.

Sign up for GitHub

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
wants to merge 3 commits into from
Closed

docs: plugins.eslint.org Website #123

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e14bc4f
docs: plugins.eslint.org Website
fasttime Aug 29, 2024
769cdae
update
fasttime Sep 5, 2024
07f0aff
suggest alternatives for open questions
fasttime Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions designs/2024-plugins.eslint.org-website/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,12 @@ Each plugin contains a `README.md` file whose content should be rendered in the
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.
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.
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?_).
Expand Down Expand Up @@ -122,13 +124,18 @@ Not relevant for this proposal.
you can remove this section.
-->

* 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
Expand All @@ -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.
Copy link
Member

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.

Copy link
Member Author

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.


## Frequently Asked Questions

<!--
Expand Down