Create a Standard Readme linter

[RichardLitt]

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.

[localjo]

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.

[localjo]

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.

[RichardLitt]

@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?

[localjo]

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?

[wooorm]

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.)?

[RichardLitt]

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.

[wooorm]

Yup, I think so too!

[localjo]

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?

[RichardLitt]

@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.

[wooorm]

👍

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?

[localjo]

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.

[localjo]

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.