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.

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

Create a Standard Readme linter #5

Open
RichardLitt opened this issue May 12, 2016 · 19 comments
Open

Create a Standard Readme linter #5

RichardLitt opened this issue May 12, 2016 · 19 comments

Comments

@RichardLitt
Copy link
Owner

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.

@RichardLitt RichardLitt mentioned this issue May 19, 2016
18 tasks
@localjo
Copy link

localjo commented Jul 28, 2016

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
Copy link

localjo commented Jul 28, 2016

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
Copy link
Owner Author

@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
Copy link

localjo commented Jul 28, 2016

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
Copy link
Collaborator

wooorm commented Jul 28, 2016

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
Copy link
Owner Author

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
Copy link
Collaborator

wooorm commented Jul 28, 2016

Yup, I think so too!

@localjo
Copy link

localjo commented Jul 28, 2016

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
Copy link
Owner Author

@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
Copy link
Collaborator

wooorm commented Jul 28, 2016

👍

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
Copy link

localjo commented Aug 15, 2016

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
Copy link

localjo commented Aug 15, 2016

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.

@ralphtheninja
Copy link

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! 🎉

@localjo
Copy link

localjo commented Aug 22, 2017

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.

@RichardLitt
Copy link
Owner Author

From mine, it isn't being prioritized at the moment, but should be in the next few months.

@piranna
Copy link

piranna commented Nov 14, 2019

What's current status of the linter?

@RichardLitt
Copy link
Owner Author

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.

@Potherca
Copy link
Contributor

Potherca commented Jan 2, 2021

It might be useful to link to https://github.com/RichardLitt/standard-readme-preset ?

@RichardLitt
Copy link
Owner Author

That would be a great idea. PRs accepted.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

10 participants
@Potherca @ralphtheninja @localjo @piranna @RichardLitt @wooorm and others