markdownlint-rule-github-internal-links

Custom markdownlint rule for checking internal links like those generated by Github's Markdown processor. Specifically, this rule checks that internal links (of the form #anchor) match the anchors generated by this anchor generation code, or manually inserted anchors via name or id attributes.

For example, in this README.md, the link #configuration will not report an error, while the link #config will. In addition, the links #enable-rule and #add-package will match the manually inserted anchors below, while the link #add-rule will report an error.

Usage

1. Add this package to your project:

   npm install -D markdownlint-rule-github-internal-links
   

2. Enable the rule:

   • If you're using markdownlint-cli, add a command-line argument to import the rule:

     markdownlint ... --rules markdownlint-rule-github-internal-links
     

     See the test:cli script in this package.json.

   • If you're using markdownlint-cli2, add a customRules element to your .markdownlint-cli2.jsonc:

     "customRules": [
       "markdownlint-rule-github-internal-links"
     ]
     

     See the sample .markdownlint-cli2.jsonc (which also turns on verbose mode, which you probably don't want), and the test:cli2 script in this package.json.

Configuration

You can pass in a setting of verbose: true to make this plugin display every anchor link it computes and every link it tests. This can be useful for debugging your anchor links, when it's hard to guess how many -s to add. See sample .markdownlint.yaml (for cli or cli2) and sample .markdownlint-cli2.jsonc (for cli2).

More Complex Example

A more complex example is the header above, which produces the link #-more-complex-example.