Create a Standard Readme linter
RichardLitt opened this issue · 19 comments
There should be a linter, after the spec in the main readme is filled out. The linter will most likely use remark and remark-lint. This is the planning issue for the linter. Please subscribe here, and open new issues for tangential questions about Standard Readme.
Hi @RichardLitt is there a linter already in progress? I started working on one that uses remark and remark-lint before discovering this conversation. Here's what I've built so far: https://github.com/SparkartGroupInc/quality-docs
It's definitely a work in progress, and not 100% in line with the standard-readme spec at the moment, but I'd be interested in making the changes to bring it in line with the spec if there's a need for it.
I've updated quality-docs to use remark's defaults and to accept a configuration file to override the default rules. The configuration file wouldn't have to be used in the case of standard-readme, but it made more sense to keep the defaults in remark rather than in quality-docs.
@josiahsprague Nice! There is a linter in progress, but I haven't gotten very far at it. I don't have much bandwidth for making the linter right now (unfortunately). quality-docs looks good from a quick glance; I think that making it standard-readme compatible would be 100% awesome.
I'm a bit confused by your second post: is the default remark's defaults, or standard-readme's (based on the spec) defaults?
The default I was referring to was remark's default. Seems reasonable to me to try to make remark-lint's defaults match the standard-readme spec. I'm assuming it's already pretty close, and I could open some PRs to update it where it's not. @wooorm what do you think?
I think you’re talking about lint defaults, right? So whether to use * or _ for emphasis?
In lieu of standard-readme being named after “standard”, it should probably have one style to rule them all. So no configuration.
That being said, not sure if @RichardLitt envisions this project, and an accompanying linter more as style linter (* or _) or an outline linter (required sections, required naming standards, etc.)?
I was thinking more of an outline linter. I don't care about style - that's useful, for some things, but largely unimportant for the purposes of humanely digesting the information of the README. As long as it is Markdown format, I am happy. In some cases, like adding a <p align="center">## Header</p>, adding HTML is fine with me, too. Also, people are really attached to their READMEs, and enforcing style will lead to a lot of bikeshedding, tiredness, and ultimately abandonment of any standard readme style, I think.
Yup, I think so too!
Ok, in that case I can add a set of rules to quality-docs that modifies the remark-lint defaults to check the standard-readme spec in a lenient way that helps people avoid bike-shedding and fatigue. I'll make it possible to override in the case that someone wants to use the linter outside of the context of standard-readme, but I'll set it up to be the default.
Any thoughts on renaming quality-docs to standard-readme-linter?
@josiahsprague That sounds good to me. If it works, renaming also makes sense! Let's rename when we have a working product; might also be smart to move the linter into this repo, like is done with feross/standard, so that we can actually download the linter with npm i standard-readme.
👍
It’s also possible to have both project alongside each other, right? In that case, quality-docs can focus on more subjective matter like readability and style, and it could work on files not called readme.md as well, where standard-readme-linter would focus just on outline of readme.md files?
I'll have to put this on the back burner for now, but now that I've gotten more familiar with the project, I'm thinking that quality-docs could be used as a dependency in a project that runs something like;
quality-docs readme.md --rules standard-readme-spec.json --silent
Where standard-readme-spec.json would be a config file tailored to match the standard-readme spec. It'd take some work to support all of the features needed for the standard-readme spec, but still probably a good start.
If someone wants to tackle this before I get back to it, feel free to open issues or PRs in quality-docs for any features that need to be added.
Any updates on this? Love this project ❤️ Was just thinking about a similar project and was really happy to see that someone else is already working on this! 🎉
From my side, I'm working on a different team now, and don't have time to work on this. But feel free to fork what's there and continue working on it. I'm happy to answer questions.
From mine, it isn't being prioritized at the moment, but should be in the next few months.
What's current status of the linter?
but should be in the next few months.
This was overly ambitious. I'm not currently working on it. I would be happy to advise on any PRs, though.
It might be useful to link to https://github.com/RichardLitt/standard-readme-preset ?
That would be a great idea. PRs accepted.