A reference implementation for running CI on Markdown files.
- markdown-ci-reference-implementation
We use the Node environment as not all of the tools used have docker images provided through the node package manager.
❗ Please Note: at this time in order to use yarn you must have a
yarn.lock file.
(See here for more)
We use the popular markdownlint library for linting our markdown files. We
will do this through the markdownlint-cli command line tool running in a
docker container for portability.
- Link to
markdownlintGitHub page - Link to
markdownlint-cliGitHub page - Link to
markdownlint-cliDocker image
We are also leaving the default ruleset. These rules can be customized see Instructions here.
docker run -v $PWD:/markdown 06kellyjac/markdownlint-cli -i node_modules **/*.md
We use the cspell tool for checking the spelling in our markdown files.
There currently is no docker image for this tool and so must be installed
through npm or yarn.
Please note: You will need to customize this command to do so follow these instructions
cspell **/*.md --color
We use the markdown-link-check to ensure that all of the links we are
referencing in our markdown file point to valid web sites. We are using
the docker image for this tool to ensure a consistent run environment.
Please Note: The markdown link checker does not have functionality to exclude folders so we are using the find command to search for all markdown that aren't in the node_modules folder.
Due to the use of find this command is best run on posix compatible operating systems
find . -not -path './**/node_modules/*' -name "*.md" | \
xargs docker run --rm --read-only -v $PWD:/data robertbeal/markdown-link-checkerThanks goes to the IT Strategy Team at ESDC. Most of this information is copied from their work in automating their markdown strategy documentation.