feat: add linting

[gadomski]

Adds markdown linting via https://github.com/DavidAnson/markdownlint-cli2. STAC extension repos use https://github.com/remarkjs/remark, but I found the Github action and CLI tooling there to be a bit more awkward — I'd prefer to not add a package.json if we don't have to.

I also added https://github.com/j178/prek for running in CI and auto-running locally ... it's my new favorite alternative to pre-commit

I ignored two rules that seemed annoying and not super helpful, line-length and "useful link text". If folks think we should enforce those, I'm happy to turn them on instead.

Closes #12

[jsignell]

Looks good to me and I agree about line length - my feeling is it just confuses the git history.

[m-mohr]

Depends. I usually try to break at ./?/!/,/;, then it often leads to less changes in the git history, but if you fill the lines til the end, it's indeed not ideal. Some lines get very long and then the diff of changes doesn't look super nice either. Having that said, the rule is annoying to some extent. So both is fine for me.

remark can also run via CLI btw, doesn't necessarily need a package.json (npx remark-cli ..., I think). But anything is fine, I guess. Remark did support GFM and link checking, does the new library support it, too?

I think "useful link text" is actually important for accessibility.

[gadomski]

remark can also run via CLI btw, doesn't necessarily need a package.json. But anything is fine, I guess. Remark did support GFM and link checking, does the new library support it, too?

🤦🏼 I didn't find https://www.npmjs.com/package/remark-cli in my searching, my bad. I'm happy to switch back, since I don't believe markdownlint-cli2 supports link checking (it's a pretty light tool).

I think "useful link text" is actually important for accessibility.

👍🏼 good point, I'll re-enable that rule and fix the links.

[m-mohr]

I'm also not 100% sure how remark-cli enables the additional external packages, probably need to be installed upfront via npm...

[gadomski]

I'm also not 100% sure how remark-cli enables the additional external packages, probably need to be installed upfront via npm...

I can't find a pre-commit hook for remark-cli (this issue indicates there isn't one: remarkjs/remark-lint#227), so I'm inclined to stick with markdownlint-cli2. I've flailed for about twenty minutes to build a custom hook and I'm finding remark kind of fiddly.

[m-mohr]

Fine for me. Can we find another tool that can check the links? I find that rather important to ensure links are no getting broken over time.

[m-mohr]

Thanks, Pete. I can't approve as it's not fully working for me. Also, it's a bit confusing that the contributing has separate steps for the markdown cli, but then to run all tests (including markdown cli again), you have to run prek.

Another issue is that the old link check did detect invalid fragments (if I recall correctly), but this one does not. That the most valuable check though.

[gadomski]

Also, it's a bit confusing that the contributing has separate steps for the markdown cli, but then to run all tests (including markdown cli again), you have to run prek.

Agreed. I removed the section about markdownlint-cli2 and just point folks towards prek.

Another issue is that the old link check did detect invalid fragments (if I recall correctly), but this one does not. That the most valuable check though.

This one does, e.g. I manually modified a link and got:

  best-practices-item.md:8:3 error MD051/link-fragments Link fragments should be valid [Context: "[Datetime selection](#datetime-selectio)"]

[m-mohr]

It seems it only checks it in the same file, but not other files...

[gadomski]

It seems it only checks it in the same file, but not other files...

Bummer. I can take another crack at going back to remark

[gadomski]

Ok, switched to remark, and copied most of the config from the stac-extensions template.

[m-mohr]

I still can't get prek running, unfortunately.

[gadomski]

Ok, no worries. Without prek, I'm inclined to abandon pre-commit hooks altogether and just provide manual instructions. I'll update.

[gadomski]

@m-mohr I removed prek and updated the linting instructions to be manual. Can't say I love all the packages that remark-lint needs (feels fiddly) but 🤷🏼

[m-mohr]

Thanks, Pete!

It's modular, so I guess that is a valid path to go.

I'm fine with merging this, but I think I'd recommend also adding a package.json so that it's easier to install. We could also add back stac-node-validator for validating the examples. I can take care of that later. => #49