/mdlint

Lint JavaScript code blocks in markdown files to find syntax errors

Primary LanguageJavaScriptMIT LicenseMIT

mdlint

Lint JavaScript code blocks in markdown files to find syntax errors.

NPM version Dependency Status Travis Status

Installation

npm install -g mdlint

Usage

mdlint [command] <arg> [options]

mdlint is used as a command-line utility. It lints markdown files sourced from different locations using the following four commands:

Commands:

glob  <fileGlob>        lints local markdown files that match a file glob
user  <username>        lints all READMEs from a user's GitHub repos
repo  <user/repo>       lints a README from a GitHub repo
query <query> [options] lints READMEs from repos returned by a GitHub query

Options:

-v, --verbose    report linting of all files
--page=<pageNum> page of results to return from query command. Defaults to 0.
-h, --help       output usage information
-V, --version    output the version number

Usage with Grunt

To integrate mdlint into your CI testing with Grunt, check out the grunt-mdlint plugin!

Sample Usage

Here is an example of mdlint being run on a set of local files. Note that the glob expression must be wrapped in quotes as * is a special character in the terminal:

mdlint glob "docs/*.md"

Here is an example of mdlint being run on all READMEs from a user's GitHub repos:

mdlint user ChrisWren

Here is an example of mdlint being run on a GitHub repo's README file:

mdlint repo ChrisWren/grunt-pages

Here is an example of mdlint being run on the collection of READMEs returned from page 2 of the grunt GitHub repositories search query:

mdlint query grunt --page=2

Usage with implicit commands

Any argument with a * or . will be interpreted as a local file glob, so you can lint a local file with the following shorthand command:

mdlint "README.md"

Any argument without a * or . that includes a / will be interpreted as a GitHub repo, so you can lint a repo with the following shorthand command:

mdlint ChrisWren/grunt-nodemon

Any other argument will be intrepreted as a GitHub user, so you could lint all of a user's repos with the following shorthand command:

mdlint ChrisWren

Accepted JavaScript Partials

mdlint accepts certain pre-defined JavaScript partials which it will preprocess so that an error isn't thrown during syntax validation.

Object partials

gruntplugin: {
  
}
{
  key: 'value'
}

Function partials

function () {
  
}

Accepted Non-JavaScript statements

  • ... will be removed from code blocks

Changelog

0.1.0 - Removed --silent flag in place for --verbose flag. By default, don't log passing markdown files, simply display a success message.

Breaking changes:

  • --silent flag no longer exists.

0.0.6 - mdlint exits with 1 when any file fails linting. Improved object partial parsing.

0.0.5 - Fixed bug where only the first error in a file was logged. Added prettier logging.

0.0.4 - Added support for implicit commands.

0.0.3 - Added ability to parse javascript code blocks.

0.0.2 - Made page parameter optional for query command.

0.0.1 - Added user command.

0.0.0 - Initial Release.