md-link-checker-teamcity

A markdown link checker. A wrapper around markdown-link-check that:

1. Finds each markdown file (*.md) in your project
2. Runs markdown-link-check on it
3. Outputs teamcity service messages and fails the build if unreachable links are found
4. Optionally, allows for white listing of links that won't fail the build if they are unreachable

Installation

To add it to your project:

npm i -D md-link-checker-teamcity

To install it globally:

npm i -g md-link-checker-teamcity

Team City Usage

Then add a task to the scripts section of your package.json:

"linkck:teamcity": "node node_modules/md-link-checker-teamcity --reporter=teamcity"

And then you can instruct your Team City build to include a step like npm run linkck:teamcity.

This will search for every markdown file in your project and check the links in each. Any dead links will be reported and will cause the build to fail.

The --reporter switch instructs the command to output errors using teamcity service messages and also is responsible for failing the build if dead links are found. Without this switch the command just prints out user friendly messages to the command line.

White Listing

It may be the case that some links in your documents cannot be reached from your build engine. A common reason for this issue is that authentication is required to access the linked file. To avoid these links from failing your build you can add them to a whitelist. They will still be reported as unreachable, but they will no longer cause the build to fail.

Modify your npm script like this:

"linkck:teamcity": "node node_modules/md-link-checker-teamcity --reporter=teamcity --whitelist=./link-whitelist.json"

Where the file link-whitelist.json is an array of links that are whitelisted:

[
    {
        "link": "http://mydomain.com/cool-file.md",
        "reason": "Authentication required"
    },
    {
        "link": "https://myotherdomain.com/",
        "reason": "Authentication required"
    },
]

Command Line Usage

To get user friendly messages simply leave off the --reporter switch.

md-link-checker-teamcity

Example Output

The following output is generated by running md-link-checker-teamcity on this project.

No Reporter and no White List

$ md-link-checker-teamcity
ERROR: 'https://__nothing_garbage.com' in file 'sample/sample-markdown.md' could not be reached.
ERROR: 'https://__whitelisted_garbage.com' in file 'sample/sample-markdown.md' could not be reached.

No Reporter but with White List

In this example the unreachable links are split into to categories: WARN and ERROR. Unreachable whitelisted links show up as warnings only. When used with teamcity they do not trigger a build failure.

$ md-link-checker-teamcity --whitelist=sample/sample-whitelist.json
WARN: 'https://__whitelisted_garbage.com' in file 'sample/sample-markdown.md' could not be reached but is whitelisted.
ERROR: 'https://__nothing_garbage.com' in file 'sample/sample-markdown.md' could not be reached.

Team City Reporter and White List

In this example we are using the TeamCity reporter so the output consists of teamcity service messages that team city can parse and display in build output.

$ md-link-checker-teamcity --reporter=teamcity --whitelist=sample/sample-whitelist.json
##teamcity[inspectionType id='LINK001' name='no-dead-links' description='Reports links that were not reachable.' category='Document issues' flowId='4772759364' timestamp='2017-11-23T17:27:53.461']
##teamcity[inspectionType id='LINK002' name='no-whitelisted-dead-links' description='Reports links that were on a whitelist. These are links that we know may not be reachable by an automated build tool. This inspection is just meant as a informational message.' category='Document issues' flowId='4772759364' timestamp='2017-11-23T17:27:53.462']
##teamcity[inspection typeId='LINK002' message='Whitelisted dead link: https://__whitelisted_garbage.com' file='sample/sample-markdown.md' SEVERITY='INFO' flowId='4772759364' timestamp='2017-11-23T17:27:54.124']
##teamcity[buildProblem description='Dead links detected.' flowId='4772759364' timestamp='2017-11-23T17:27:54.124']
##teamcity[inspection typeId='LINK001' message='Dead link: https://__nothing_garbage.com' file='sample/sample-markdown.md' SEVERITY='ERROR' flowId='4772759364' timestamp='2017-11-23T17:27:54.124']

The first two messages are used to register inspection types with Team City. The third message reports a Whitelisted dead link which has a severity of INFO. The next message reports a build problem and this is what actually fails the build. This message was generated because of the existence of a non-whitelisted dead link which is reported in the last message with a severity of ERROR.

Using in Pull Requests

This tool was written to be used in builds triggered by pull requests. It's default behavior is to check all files in a directory. If you wish to use it in a build you can use the --changed switch to only check those markdown files that have changed in this pull request (vs. master).