Currently in the middle of porting a large-ish web documentation site from janky, old style, MS Word generated html to standard markdown so I can use it as content for an 11ty site.

Of course, all the html is broken in different ways and written over time in various different styles so running a conversion tool on it proved to be a problem. I have been migrating it piece by piece by writing simple command line conversion tools to address one problem at a time and the bits that are too difficult to automate I am hand converting.

This lead me to finding a tool to run against all my pages to make sure that the markdown is correct and I don't have any stray html markup where I don't want it. The tool is a package called markdownlint which I run as a script from npm using markdownlint-cli.

{
  "scripts": {
    "lint": "markdownlint --config .markdownlint.json content/DOC*.md"
  },
}

It works very much like other lint varieties in other languages but I found it very useful to (as the command line allows) use a config file to turn on and off issues while I make gradual improvements to the docs.

{
  "no-trailing-spaces": false,
  "no-hard-tabs": false,
  "line-length": {
    "line_length": 100
  },
  "no-inline-html": {
    "allowed_elements": [
      "a",
      "p",
      "h4",
      "caption"
    ]
  },
  "no-multiple-blanks": false
}

Configuration can be single options on or off or objects with embedded configuration to override the defaults, like the line-length and allowed_elements above.

Part way through the conversion means I have to relax some issues generally, turn off checking on some files and override small sections where there is no other option.

Turning off checking in a draft/broken source file you can put a single comment tag at the beginning of the file like this:

<!-- markdownlint-disable-file -->

<dodgy_html />

Specific issues can be "accepted" by adding an exception a line above:

<!-- markdownlint-disable-next-line line-length -->
This is too long a line to show up correctly in the doc....

For more extreme cases where more than one line in a block is causing a violation, then capturing the current state, disabling checking then restoring at the end is a good solution.

<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
<oUteRagousHtmlCode>
    <goeSHEere />
</oUteRagousHtmlCode>
<!-- markdownlint-restore -->