docs-checker
is a tool for identifying markdown documentation structures and verifying that they follow the same pattern provided by the user. Curious to know how?
- docs-checker uses
markdown-it
for markdown analysis - docs-checker uses an AST with regex to evaluate patterns in the documentation structure
- docs-checker uses
moenda
an engine responsible for executing the rules.
docs-checker
is also flexible, so if you want to create your custom rule, follow this guide.
Prerequisites:
You can install docs-checker using npm:
$ npm install docs-checker
Then you will be able to use the package running the following command:
$ ./node_modules/.bin/docs-checker run <files.md>
You'll get an output similar to that:
Because docs-checker is designed to be flexible and configurable for your use case, you can specify your own configuration rather than follow the default one. Using a JSON file named config.json
, you can specify rules and it's configs as showed below:
config.json
{
"rules": {
"require-structure": {
"h1": {"p": "required"},
"h2": [{"p": "required", "h3": "optional"}, {"h3"}]
},
}
}
You can also turn off any rule that you want using "false" on the configs, or by providing a comment on markdown
config.json
{
"rules": {
"require-structure": false
}
}
markdown inline config
<!--docs-checker-disable require-structure-->
Currently docs-checker
has only one rule, require-structure
. This rule is responsible to check if a markdown documentation follow the structure specified.
Each rule is represented by a single object with some properties and one method.
module.exports = {
name: 'my-great-rule',
tags: ['md', 'docs'],
description: 'Checks if documentation contains title',
run: function rule(params, onError){
// ..
}
};
name
- The rule name. This is used as an identifier to configure docs-checker on the command line.tags
- A human readable list of tags that help other users to identify what this rule is about.description
- A human readable description for the rule. This is used in the cli to describe the rule.run
- The one method is run(), which sets up the rule. This method is passed with two arguments,params
and areporter
function.params
includes two objects, context and rule configs. Thecontext
object contains additional functionalities that is helpful for rules to do their jobs, is a result ofparser
processing while the rule configs are the configs provided by the user usingconfig.json
file. Thereporter
is a function used to report a problem in the structure.
After define your custom rule you'll need to define where those rules are located in your config.json
file
{
"custom-rules": "path/to/my-rules-module",
"rules": {
"require-structure": {
"h1": {"p": "required"},
"h2": [{"p": "required", "h3": "optional"}, {"h3"}]
},
}
}