Skip to content
This repository has been archived by the owner on Sep 20, 2023. It is now read-only.

add: markdown linting 101 #452

Open
CouldBeThis opened this issue Nov 29, 2020 · 0 comments
Open

add: markdown linting 101 #452

CouldBeThis opened this issue Nov 29, 2020 · 0 comments

Comments

@CouldBeThis
Copy link
Contributor

I was not familiar with the concept of "linting" so the documentation on the readme.md about markdown linting (added/described in #283) went in one eyeball and out the other when I initially read it.

I am uncertain how much detail should be included on that page and didn't want to fill it up with all these details unless it is appropriate so instead I am creating an issue for discussion.

what is linting

There should be at least a short explanation of the relevance such as this one I found

Linting is the process to check code for potential errors and enforce a style guide, but linting is not just for code; you can lint markdown documents for the same reasons.

source: mkaz.blog (no license details found)

linting is mandetory

And to be clear about it something along the lines of

Any edits to the documentation will be checked for lint [ ? or linted ? ] automatically and will not be approved until it passes the check. Please perform this check prior to making pull requests.

If your text is creating errors you think are incorrect please open an issue.

how to & workflow

The document contains instruction on how to install this in VS Code. DavidAnson/markdownlint's readme has information on other options. (I guess but am not certain that these are all mutually compatible using the same MD rules.) Might be handy to include a link or the information itself.

If I understand properly, this tool is installed somehow in the repo so that MD files submitted via pull requests are magically checked. (Cool!)

  1. Is it possible to use the repo's implementation rather than running locally? Like is there a dry run ability so I could pre submit changes and see errors that would be generated?
  2. Is there a way that I can see errors created by my own pull request? (Instead of waiting for someone else to comment and tell me which is how I found last time?)
  3. Is there any documentation available for how to use this tool if a person is not using CLI? (web and/or desktop)

If neither (1) nor (3) are possible then perhaps linking explicitly to a web-based implementation such as markdownlint demo would encourage use.

If anyone has links to materials about workflow with this tool it would be useful (to me at least).

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Development

No branches or pull requests

1 participant