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.
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
You can invoke foliant-md-linter in a Foliant building process.
-
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
-
- 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
- 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
...
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
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