search

sb2nov / mac-setup

Installing Development environment on macOS
https://sourabhbajaj.com/mac-setup/
Other
7.15k stars 1.02k forks source link

Run markdownlint on CI #240

Closed hugovk closed 5 years ago

hugovk commented 5 years ago

Fixes #239.

This installs and runs the command-line interface for markdownlint.

Well, at the moment, there's a LOT of lint errors!

https://travis-ci.org/hugovk/mac-setup/builds/478022235#L754

643 to be exact:

$ markdownlint . 2>&1 |  wc -l
     643

Here's a count by category:

   5 MD006/ul-start-left Consider starting bulleted lists at the beginning of the line
  13 MD007/ul-indent Unordered list indentation
   3 MD009/no-trailing-spaces Trailing spaces
  17 MD012/no-multiple-blanks Multiple consecutive blank lines
 209 MD013/line-length Line length
 144 MD014/commands-show-output Dollar signs used before commands without showing output
 127 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines
  13 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content
   4 MD025/single-h1 Multiple top level headings in the same document
   1 MD028/no-blanks-blockquote Blank line inside blockquote
   9 MD029/ol-prefix Ordered list item prefix
  13 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines
  41 MD032/blanks-around-lists Lists should be surrounded by blank lines
  30 MD033/no-inline-html Inline HTML
   1 MD034/no-bare-urls Bare URL used
   7 MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading
   5 MD040/fenced-code-language Fenced code blocks should have a language specified
   1 MD042/no-empty-links No empty links

Are there any of these that should definitely be turned off right away? Or any that can be adjusted (eg. increase line-length a bit)?

I'd suggest tweaking the config a bit, fixing a few of the low-hanging fruit, then temporarily ignoring the others to get the CI to pass. Then the others can be tackled in batches one-by-one in their own PRs.

hugovk commented 5 years ago

Ignoring "MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content" because it complains about repeated headers like this, which I think are completely fine here:

App1

Installation

...

Usage

...

App2

Installation

...

Usage

...

hugovk commented 5 years ago

If using VS Code, I recommend the markdownlint (davidanson.vscode-markdownlint) extension, it shows you linting errors with a squiggly green underline and tooltips.

Down to 404 errors:

   5 MD006/ul-start-left Consider starting bulleted lists at the beginning of the line
  13 MD007/ul-indent Unordered list indentation
 208 MD013/line-length Line length
 144 MD014/commands-show-output Dollar signs used before commands without showing output
   2 MD028/no-blanks-blockquote Blank line inside blockquote
   9 MD029/ol-prefix Ordered list item prefix
  14 MD032/blanks-around-lists Lists should be surrounded by blank lines
   1 MD034/no-bare-urls Bare URL used
   7 MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading
   1 MD042/no-empty-links No empty links
simeg commented 5 years ago

@hugovk Awesome of you to pick this up! 😄I think your proposed strategy sounds good. If only the linter had a --fix flag 😛

Kyslik commented 5 years ago

I actually asked a few months ago about that --fix https://github.com/DavidAnson/vscode-markdownlint/issues/13#issuecomment-319719437 (for the VSC extension).

hugovk commented 5 years ago

Any comments about the remaining errors? Fix, tweak or ignore?

   5 MD006/ul-start-left Consider starting bulleted lists at the beginning of the line
  13 MD007/ul-indent Unordered list indentation
 208 MD013/line-length Line length
 144 MD014/commands-show-output Dollar signs used before commands without showing output
   2 MD028/no-blanks-blockquote Blank line inside blockquote
   9 MD029/ol-prefix Ordered list item prefix
  14 MD032/blanks-around-lists Lists should be surrounded by blank lines
   1 MD034/no-bare-urls Bare URL used
   1 MD042/no-empty-links No empty links

You can see the context from https://travis-ci.org/sb2nov/mac-setup/builds/478347674#L457.

If not, I'll disable those for the time being.

Kyslik commented 5 years ago

I think we can use allow_failure https://docs.travis-ci.com/user/customizing-the-build/#rows-that-are-allowed-to-fail instead of disabling the rules.

hugovk commented 5 years ago

If we allow failures then new PRs will introduce new linting errors and no-one will notice.

A build failure is a sure way to prevent new errors.

simeg commented 5 years ago

I'd be happy to ignore the rest and we can work through them one-by-one. It's not like these linting errors are critical in any way. Great work on this PR!

Kyslik commented 5 years ago

Maybe we can ignore MD013 (Line length).

hugovk commented 5 years ago

And we're green!