Foliant markdown linter

Wrapper-script for running markdown linters in Foliant projects.

This script uses:

• markdown-link-check
• markdownlint with
  • markdownlint-cli2
  • markdownlint-foliant-rules for specific Foliant checks.

Installation

Locate your foliant project:

cd my-awesome-foliant-project/

Install foliant-md-linter via npm. Locally or globally, as you wish.

npm i foliant-md-linter

Include foliant-md-linter into Foliant build

You can invoke foliant-md-linter in a Foliant building process.

Prerequisites

• Install foliant-md-linter into your Docker-image if you're using a building within Docker:

  RUN npm i foliant-md-linter -g

• Install runcommands preprocessor if you haven't installed it yet:

  • native install

    pip install foliantcontrib.runcommands

  • docker install

    RUN pip3 install foliantcontrib.runcommands

1. Add runcommands to the preprocessors part of the foliant.yml:

preprocessors:
    - runcommands:
        commands:
            - cd ${PROJECT_DIR}
            # use thr project title for the p argument
            # use the l flag if using foliant-md-linter within docker
            - foliant-md-linter styleguide -v -p my-awesome-foliant-project -s src -l

2. Build you project as usual and check the output for foliant-md-linter messages.

$ foliant make site --with mkdocs
Parsing config... Done
Applying preprocessor runcommands... markdownlint-cli2 v0.4.0 (markdownlint v0.25.1)

Finding: src/**/*.md
...
Found 5 styleguide and formatting errors
Full markdownlint log see in /usr/src/app/.markdownlint_full.log

removing /usr/src/app/.markdownlint-cli2.jsonc ...

Done
Applying preprocessor mkdocs... Done
...

Usage

Run foliant-md-linter from the project root with following commands and options

• full-check Check md files with markdownlint and markdown-link-check

  • -v, --verbose Print full linting results (default: false)

  • -s, --source <path-to-sources> specify source directory (default: src)

  • -c, --config Do not create a new markdownlint config file and use default or one in root directory instead (default: false)

  • -p, --project <project-name> specify project name

  • -d, --debug print executing command (default: false)

  • -f, --allowfailure allow exit with failure if errors (default: false)

    helpful in CI/CD, as you can cause pipelines to fail in case of linting errors

  • -l, --clearconfig remove markdownlint config after execution (default: false)

    helpful within docker, otherwise annoying bugs are occurred with the markdownlint extension for VSCode

• essential Check md files for critical formatting errors with markdownlint and validate external links ith markdown-link-check

  • -v, -s, -c, -p, -d, -f, -l

• urls Validate external links with markdown-link-check

  • -v, -s, -d, -f, -l

• styleguide Check for styleguide adherence with markdownlint

  • -v, -s, -c, -p, -d, -f, -l

• slim Check for critical errors with markdownlint

  • -v, -s, -c, -p, -d, -f, -l

• fix Fix formatting errors with markdownlint

  • -v, -s, -c, -p, -d, -f, -l

• typograph Fix typograph errors with markdownlint

  • -v, -s, -c, -p, -d, -f, -l

• print Print linting results

  • -v

• create-full-config Create markdownlint config for styleguide adherence

  • -s, -p, -d

• create-slim-config Create markdownlint config for critical errors check

  • -s, -p, -d

• create-typograph-config Create typograph config for typograph errors check

  • -s, -p, -d

Examples

The simplest case

$ npx foliant-md-linter full-check

Checked 2 files
Found 8 critical formatting errors
Full markdownlint log see in /Users/user/github/foliant-md-linter/.markdownlint_slim.log

Found 9 styleguide and formatting errors
Full markdownlint log see in /Users/user/github/foliant-md-linter/.markdownlint_full.log

Found 2 broken external links
Full markdown-link-check log see in /Users/user/github/foliant-md-linter/.markdownlinkcheck.log

If you want more detailed output

$ npx foliant-md-linter full-check -v

Checked 2 files
Found 8 critical formatting errors

--------------------------------------------------------------------------------

FILE: src/linter-test-A.md

src/linter-test-A.md:3 MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]
src/linter-test-A.md:7 indented-fence Fenced code shouldn't be indented by 1 to 3 spaces [Context: "   ```bash"]
src/linter-test-A.md:11 non-literal-fence-label Invalid language label in fenced code block
src/linter-test-A.md:18 fenced-code-in-quote Fenced code shouldn't be in quote
src/linter-test-A.md:26 validate-internal-links Broken link [image does not exist] [Context: "/red-circle.png"]
src/linter-test-A.md:30 validate-internal-links Broken link [file does not exist] [Context: "/another-project/subproject/article"]
src/linter-test-A.md:32 validate-internal-links Broken link [file does not exist] [Context: "/another-project/subproject/article#anchor"]

--------------------------------------------------------------------------------

FILE: src/subproject/article.md

src/subproject/article.md:3 validate-internal-links Broken link [invalid local anchor] [Context: "#anchor"]

Full markdownlint log see in /Users/user/github/foliant-md-linter/.markdownlint_slim.log

Found 9 styleguide and formatting errors
Full markdownlint log see in /Users/user/github/foliant-md-linter/.markdownlint_full.log

Found 2 broken external links

--------------------------------------------------------------------------------

FILE: src//linter-test-A.md

  [✖] https://github.com/holamgadol/foliant-md-lint → Status: 404

--------------------------------------------------------------------------------

FILE: src//subproject/article.md

  [✖] https://github.com/holamgadol/foliant-md-linte → Status: 404

Full markdown-link-check log see in /Users/user/github/foliant-md-linter/.markdownlinkcheck.log

If project sources are located in a folder other than src, then you may specify them via -s option

$ npx foliant-md-linter full-check -s another-sources

Sometimes, the project directory and the project name could be different, especially inside docker containers. You have an option to specify the project name to validate absolute links properly

$ npx foliant-md-linter full-check -p project-name

You can edit a generated .markdownlint-cli2.jsonc config file for your needs and use it for the next markdownlint runs by -c option

$ npx foliant-md-linter full-check -c