add more detailed explanation of usage

[MFTabriz]

I'm using the latest docker image (v0.32.1) The CLI usage is described as

Usage: markdownlint [options] <files|directories|globs>
…
--disable [rules...] Disable certain rules, e.g. --disable MD013 MD041

According to this explanation, if I want to disable a certain rule, the command line should look like:

markdownlint --disable MD013 docs/*.md

but apparently that does not work. I had to run it as either:

markdownlint --disable MD013 -- docs/*.md

or

markdownlint docs/*.md --disable MD013

If this is the right way to pass the args through CLI, please update the documentation.

[DavidAnson]

If you put single quotes around the glob in the original attempt, I think that will work. The fact that adding "--" made a difference suggests you are fighting with your shell's argument passing behavior here. It's not reasonable to document the behavior of every different shell; that's info the user will be more familiar with.

[MFTabriz]

Thanks for your quick response.

It's not reasonable to document the behavior of every different shell; that's info the user will be more familiar with.

Fair enough! But I’m using the ghcr.io/igorshubovych/markdownlint-cli:latest container image which comes with a shell provided by the project itself.

[MFTabriz]

Looking at the dockerfile, the shell must be alpine's ash.

[DavidAnson]

Sorry! I realized in the shower I may have come to the wrong conclusion. The rules parameter is a list and that may be what's requiring the double dashes to end the list. I'm not super familiar with the command line parser used by this project, so I didn't realize at first. I think you are probably right this should be documented better!