mike42 / mdcheckr Goto Github PK

5.0 3.0 7.0 46 KB

Practical CI testing for markdown files

License: Other

Shell 92.77% Roff 6.38% Makefile 0.85%

markdown testing

mdcheckr's Introduction

mdcheckr

mdcheckr is a testing tool to detect quality problems with your Markdown documentation. It is designed to act as a quality gate in your continuous integration pipeline.

Syntax errors in code blocks - Syntax-check code blocks that identify their language. Currently works for:
- bash (example)
- PHP (example)
Code blocks- Detection of un-closed code blocks (example)
Broken links- Flag files that link to relative paths or URLs on the internet which can't be accessed (example, example).
Broken images- Detect broken embeds, local and remote (example, example).

This tool is not intended to enforce a code style, and will not critique aspects of your Markdown code which do not affect the output.

Dependencies

Requirements:

curl
xmllint
pandoc

Installation

Operating systems

Ubuntu

These may be installed from the mike42/mdcheckr PPA (Notes for Travis CI users: Installing Dependencies)

sudo add-apt-repository -y ppa:mike42/mdcheckr
sudo apt-get update
sudo apt-get -y install mdcheckr

Debian

Fetch the Debian package from releases.

sudo dpkg -i mdcheckr_x.y-z_all.deb
sudo apt-get -f install

Redhat-based distrbutions

Fetch the RPM package from releases.

yum -y install epel-release
yum -y install which pandoc libxml2 mdcheckr-x.y-z.noarch.rpm
ln -s /usr/bin/mktemp /usr/bin/tempfile

This package should be considered a preview only, and is currently being produced with Alien.

Apple Mac OS distributions

You will still need to follow "install from source" instructions. However you need to ensure the dependency of Pandadoc is installed on your mac. Pleasse ensure you have homebrew installed first.

brew update
brew install pandoc
curl https://raw.githubusercontent.com/mike42/mdcheckr/master/mdcheckr -o mdcheckr
chmod +x mdcheckr
sudo mv mdcheckr /usr/local/bin

Install from source

If the dependencies are available on your system, just copy the shell script itself to /usr/local/bin:

curl https://raw.githubusercontent.com/mike42/mdcheckr/master/mdcheckr -o mdcheckr
chmod +x mdcheckr
sudo cp mdcheckr /usr/local/bin

Usage

mdcheckr [ -h | --help ] [ -v | --version ] FILE ..

Examples

Check a single markdown file:

mdcheckr README.md

Check all the markdown files in the current directory:

find . -name '*.md' -print0 | xargs -0 mdcheckr

Check all the markdown files in your Git repository:

git ls-files | grep '\.md$' | tr '\n' '\0' | xargs -0 mdcheckr

mdcheckr's People

Contributors

Stargazers

Watchers

Forkers

budziq koconder mminestrelli digitronik decanus vacp2p ilgoncalves

mdcheckr's Issues

Include line numbers in broken link messages

Currently, broken links all appear as line "1" (the script doesn't know which line the link came from).

Do some grep magic to try to point to where links came from in the original file, and only use 1 as a fallback.

Write install instructions

Direct to OS:

Ubuntu
Debian
RPM-based distros

CI systems:

Travis CI builds

Hi, I have identified a false negative on the following project: https://github.com/rust-embedded/cortex-m-rt
Would it be possible to fix this? I have no idea why it is failing though as if you copy the link it works fine.

Thanks!

Output:

$ mdcheckr README.md                                                                                                                  [12:54:15]
Checking README.md ..
- Link https://crates.io/crates/cortex-m-rt [ FAIL ]
Warning:README.md:1:Broken link 'https://crates.io/crates/cortex-m-rt'
- Link https://crates.io/crates/cortex-m-rt [ FAIL ]
Warning:README.md:1:Broken link 'https://crates.io/crates/cortex-m-rt'
- Link https://github.com/rust-embedded/wg#the-cortex-m-team [ OK ]
- Link https://docs.rs/cortex-m-rt [ OK ]
- Link LICENSE-APACHE [ OK ]
- Link http://www.apache.org/licenses/LICENSE-2.0 [ OK ]
- Link LICENSE-MIT [ OK ]
- Link http://opensource.org/licenses/MIT [ OK ]
- Link CODE_OF_CONDUCT.md [ OK ]
- Link https://github.com/rust-embedded/wg#the-cortex-m-team [ OK ]
- Image https://img.shields.io/crates/v/cortex-m-rt.svg [ OK ]
- Image https://img.shields.io/crates/d/cortex-m-rt.svg [ OK ]
Done, with 2 problems(s) found.

Possible issue with Ubuntu Precise

Noticed in install log that markdown_github support may not be available:

Checking foo.txt ..
pandoc: Unknown reader: markdown_github
/usr/bin/mdcheckr: line 35:  7875 Segmentation fault      xmllint --nowarning --html --xpath '*//a/@href' "$_inp_file" 2> /dev/null
/usr/bin/mdcheckr: line 44:  7879 Segmentation fault      xmllint --nowarning --html --xpath '*//img/@src' "$_inp_file" 2> /dev/null

RPM package

Produce an RPM package numbered 1.0

'Alien' tool could produce a starting point, or the conversion could be automated (very simple package!). Install has not been tested, but steps are something like-

apt-get install alien
alien -r mdcheckr_1.0-1_all.deb --veryverbose --generate
nano mdcheckr-1.0/mdcheckr-1.0-2.spec
.. add summary
(cd mdcheckr-1.0; rpmbuild --buildroot='/home/mike/workspace/mdcheckr/mdcheckr-1.0' -bb --target noarch 'mdcheckr-1.0-2.spec')

warning during check

After running mdcheckr README.md I got the following:

[WARNING] Deprecated: markdown_github. Use gfm instead.

A quick Google brought me to this GH Issue: Ecodev/redmine_convert_textile_to_markown#8

Ad then a quick search in this repo found it here:
https://github.com/mike42/mdcheckr/blob/master/mdcheckr#L39

Recommending changing markdown_github to gfm.