tjw-markdownlint-rules

TJW-MarkdownLint-Rules

The Jared Wilcurt's very agressive Markdown Linting rules for obsessives.

How to use this

• Create a file called .markdown-lint.yml and set it up like so:

  ---
  
  extends: ./node_modules/tjw-markdownlint-rules/tjwmarkdownlint.yml
  # Override the proper-names rule to enforce capitalization of your project's name and other proper nouns
  proper-names:
    names:
      - JavaScript
      - Your Project Name
  

• Put the .markdownlint.yml file in your project root (next to package.json)

• npm install --save-dev markdownlint-cli tjw-markdownlint-rules

• In the "scripts": section of your package.json add in these two lines:

  • "markdownlint": "markdownlint -i \"./node_modules/**/*\" --config ./.markdownlint.yml ./**/*.md"
    • Note: You can change the ./**/*.md to be specific to your project's folder structure. Example: docs/**/*.md

• npm run markdownlint - This will list the lines of each file that are in violation of the linting rules for you to manually correct.

Customizing rules

• Edit the .markdownlint.yml file
• Add in rules you want to override
  • In the example above, we are overriding the proper-names rule
• All rules are documented here:
  • MarkdownLint Rule Documentation

Known issues

Improper indentation not flagged:

May be covered by: #138

1. Text

    ![This should be flagged for starting with 4 spaces instead of 2](file.png)

1. Test

Trailing whitespace not caught in unordered list empty line:

#216

* Example
  * There are two spaces on the next line
  
  * The line above this should be flagged for trailing whitespace

Unfixible issues

Random indentation forced by CommonMark for sublists

The complete morons over at CommonMark, have decided to incorrectly parse list items because "reasons" (read: opinions, of which, that are the type of "bad").

1. Top level ordered list

  * Sublist with 2 space indentation
  * CommonMark only parses this as a sublist if it starts with 3 spaces. You know? 3 spaces? A super normal amount of spaces for indentation that normal people who aren't fucking idiots would totally use. Yup. 3 spaces. That's the hill they are choosing to die on. Totally valid. Not fucking stupid at all.

25. Top level ordered list

  * Sublist with 2 space indentation
  * CommonMark only parses this as a sublist if it starts with 4 spaces. Oh good, it's actually a variable amount of spaces. Even fucking better. I sure do love indentation that varies by single character increments. I'm really happy I use a linter to ENFORCE INCONSISTENCIES.

116. Top level ordered list

  * Sublist with 2 space indentation
  * CommonMark only parses this as a sublist if it starts with 5 spaces. fuck everything

Since MarkdownLint relies on markdown-it, which is built on top of the horrible "CommonMark" version of markdown, you are stuck with this shitty bullshit. I have enabled the MD006 to catch this if your code uses shitty CommonMark to be processed to HTML. However if you use a good markdown interpreter, then you should turn MD006 off, because it will try to make you over-indent to satisfy MarkdownLint's internal interpretter (markdown-it), and likely fuck up something else.

To disable it, add this to your .markdownlint.yml:

# MD006 - Consider starting bulleted lists at the beginning of the line.
# Thankfully, we do not use CommonMark. Unfortunately MarkdownLint does,
# so we have to disable this so it doesn't freak out about bullets inside numbered lists.
ul-start-left: false