Doc Link Checker verifies links in your documentation. Primarily, this is targeted at verifying internal (relative) references, to ensure broken links are detected early.

This is the CLI tool, built on top of the underlying doc-link-checker package.

At the moment the detection is limited to links and definitions in Markdown files only. Future support for images and link references is planned, as well as reStructured Text support. Please see the ideas list for other currently planned features.

Doc Link Checker is 100% native Typescript.

With yarn:

$ yarn add doc-link-checker-cli

Or with npm:

$ npm add doc-link-checker-cli

This installs a binary named doc-link-checker. You may run this using yarn run or npm run, or directly in the node_modules/.bin folder, or as a global install.

Currently the program has a single command: lint. To use all of the defaults, run this with no other arguments:

doc-link-checker lint

It will automatically scan for all Markdown files in the current working directory, and report on all of them. The default output looks a bit like this:

README.md [OK]
-- CONTRIBUTING.md --
line 20: ../README.md (Link references a file outside of the base directory.)
docs/support.md [OK]
-- docs/new-doc.md --
line 5: ../nope.md (Link references a file that does not exist.)
docs/test.md [OK]
-- docs/faq.md --
line 12: ../README.md#nope (Link references a non-existent header.)
other-docs/something.md [OK]
other-docs/another-thing.md [OK]

To run the program for a different directory, simply pass it as a positional argument:

doc-link-checker lint /path/to/docs

By default it excludes common directories that hold vendor code, such as node_modules and venv. You can control what files are included or excluded by using --include and --exclude:

doc-link-checker lint --include 'docs/**/*.md' --exclude 'docs/exclude-me/**/*.md'

Note how the glob strings are single-quoted. This prevents your shell from interpreting them, ensuring that doc-link-checker can parse them. This is important for correct operation.

Use of the --include or --exclude flags overrides the default inclusion and exclusion globs. If instead you just want to extend these defaults, you can use --include-extend and --exclude-extend instead:

doc-link-checker lint --include-extend '**/*.mark' --exclude-extend '**/hidden/**'

Instead of specifying lots of glob string as individual flags, you can store these in separate files and use them directly. If you just want to use your .gitignore file, there's a dedicated flag for that:

doc-link-checker lint --use-gitignore

If you want to use other files, you can pass --ignore-file:

doc-link-checker lint --ignore-file .dlcignore

This flag can be passed as many times as you want.

Please note that these flags have known performance issues at the time of writing:

https://github.com/sindresorhus/globby/issues/50

Globbing is case-insensitive by default. To make it case-sensitive, pass the --case-sensitive flag:

doc-link-checker lint --case-sensitive

By default, Markdown is parsed using the CommonMark spec. If your Markdown is targeting Github, or you're using Docusaurus, you should specify gfm as your Markdown type:

doc-link-checker lint --md-type gfm

This can also be configured with the environment variable DOC_LINK_CHECKER_MDTYPE.

If for some reason you need to control exit codes, you can do so with --success-code and --failure-code. They default to 0 and 1 respectively.

doc-link-checker lint --success-code 42 --failure-code 13

Customising the failure exit code only has an impact when everything else performs correctly, and linting issues are discovered by the checker. If something else goes wrong, the value specified by --failure-code is not used. An example of this is when the supplied directory to scan does not exist.

For a full description of errors that may be displayed, check the upstream Doc Link Checker readme.

Note that the checker currently makes no attempt to verify URLs.

This project aims to follow semantic versioning.

• The CLI is the only public API. The code itself is not covered by any BC promises, and may change at any time for any reason.
• The CLI arguments in the lint command will only change with major version bumps.
• The output of the lint is not currently guaranteed to be stable. In future, it may be possible to utilise different reporters with different output, some of which may be declared as stable.
• What the lint command reports as an error may change with minor version bumps. The maintainers endeavour to ensure it will not change with patch version bumps, except where there are genuine bugs or regressions in behaviour.

The code is written in Typescript. You can check that the code compiles sucessfully by running tsc like so:

$ yarn run build

The tool xo is used for linting the code. This wraps eslint and prettier with a strict set of default rules. You can run xo like so:

$ yarn run lint

At the moment, this package is mostly a thing wrapper around the underlying doc-link-checker package. If you find any issues with detection of files or handling of links, the issue is likely to be upstream:

https://github.com/djmattyg007/doc-link-checker

All contributions are welcome! Please make sure that any code changes are accompanied by updated tests. I also recommend running prettier before committing, like so:

$ yarn run reformat

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.