chore(website): generate rule docs h1 and description automatically #5249
Conversation
|
Thanks for the PR, @JoshuaKGoldberg! typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community. The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately. Thanks again! 🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint. As a thank you, your profile/company logo will be added to our main README which receives thousands of unique visitors per day. |
✅ Deploy Preview for typescript-eslint ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
| }, | ||
| ], | ||
| type: 'blockquote', | ||
| } as mdast.Blockquote); |
There was a problem hiding this comment.
Docusaurus adds an h1 automatically if the file doesn't already start with one. So all we need to add is the description.
There was a problem hiding this comment.
- Maybe use a paragraph instead of a quote?
- Add this to the
RuleAttributescomponent instead of in Markdown? Thedescriptionis already part of the rule metadata available on client side.
There was a problem hiding this comment.
I like it as a quote though 😄: it adds subtle differentiation and matches the ESLint docs.
For RuleAttributes, that shows up after any existing initial paragraph 😕 so it would be out of order:
|
i'm not sure about this one, docs at this point is slowly starting unusable in github |
I think the idea is that the docs should not be viewed on GitHub but should be as maintainable as possible. |
if that is a case than we should move it out of eslint-plugin to docs |
|
Yeah, this brings up a good point - it seems like #4980 is going to be particularly relevant now that the |
| @@ -1,7 +1,3 @@ | |||
| # `your-rule-name` | |||
There was a problem hiding this comment.
@armano2 starting a thread for #5249 (comment):
I think the idea is that the docs should not be viewed on GitHub but should be as maintainable as possible.
if that is a case than we should move it out of eslint-plugin to docs
I think I agree, it would be best long term to have these docs files in the docs area. But: the old .md files still have much better SEO than the site. We can't move them all-up just yet. The most we could do would be to leave a .md file in the old location with just the redirect notice.
What would you prefer I do in this PR? I don't have strong feelings one way or another, as long as we're moving towards automating more of the rule docs pages.
There was a problem hiding this comment.
Personally - I think it's still a good idea to co-locate them with the plugin - that way they're easy to find and update for contributors.
There was a problem hiding this comment.
I am 100% behind treating the .md files in the repo as source code for most things (i.e. users shouldn't read them).
It's what I said a year ago with the first versions of the website!
Also LMAO I had a different opinion back then about where to put the files:
TBH - I also don't see any tangible value in co-locating the docs with the packages.
So I'll say - I don't mind either way. As long as we keep things clearly documented for contributors (i.e. tests to fail if they've not been added, or not been deleted) - then it shouldn't matter.
PR Checklist
Overview
Continues the general work started in #5085 around automating the base template for rule docs. This time the
#h1 and next description are added automatically. I changed the format a bit to match the non-code h1 and slightly different description from ESLint rule docs: e.g. https://eslint.org/docs/latest/rules/array-callback-return.Followups that could be filed as issues:
## Rule Details