foliant-md-linter v0.1.12

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
  
    ```bash
    pip install foliantcontrib.runcommands
    ```
  
  - docker install
  
    ```dockerfile
    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