Feature Request: Add a linter for the docs

[tushar5526]

Is your feature request related to a problem? Please describe.

I observed that we are merging a lot of faulty PRs(broken links, garbage data in README) due to manual reviews. Linting will help us in reviewing new PRs and there are other benefits.

Linters help in SEO optimisations, checking broken links and following industry standards that helps a lot in maintaining uniformity.

Describe the solution you'd like.

Add a GHA linter for docs repo, that runs on each Pull request and also add steps in contributing guide to locally test the code through linter.

Describe alternatives you've considered

No response

Additional context.

https://github.com/p5py/p5/pull/268 I had implemented a linter once and it helped us a lot in identifying the errors beforehand.

[tushar5526]

@joewxboy I will do it if it's a ✅ from your end.

[joewxboy]

You'd have to find a linter that either:

• validated the Markdown files with inline Liquid templating

• or -

• waited until after GitHub Pages GHA ran, and then validated the generated output. We already have one that will do that for merged PRs. Maybe what you want is to run it on the PR's branch before it is merged to check the output?

[Abhijay007]

Hi, @Rene-Ch1 @johnwalicki I am working on this issue. I am thinking about implementing linter using this GHA: https://github.com/marketplace/actions/my-markdown-linter let me know your thoughts on this :)

[johnwalicki]

This markdown linter GHA looks interesting. We would likely start off with a config file that is permissive and tweak the linter settings.

I'm going to run it against a local clone of the OH docs repo to see how many linter warnings it generates.

[Abhijay007]

@dipesh-rawat Can you please look into this issue? , you can take reference from this PR https://github.com/open-horizon/open-horizon.github.io/pull/268, and if needed you can cherry-pick some of my commits.

[johnwalicki]

I propose we close this issue and PR #268 ? It's a great idea but implementation seems to be difficult because of all the preprocessor / front-matter directives. Over the past year I've crawled my way through most of the 135 markdown files in this repo. As I touched these docs, I've done a good amount of lint and formatting updates. VSCode gives you visual ques on common lint issues.

I would love to see an automated linter warning

I did a quick grep of a common lint issue and see just 7 files that need attention. I'll open an issue to review / fix those.

[joewxboy]

I second the closing proposal. @Abhijay007 any objections?

[joewxboy]

OK, hearing no objections, I'll close this issue