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 <path-to-sources>
– path to custom config -
-p
,--project <project-name>
– specify project name -
-d
,--debug
– print executing command (default: false) -
-a
,--allowfailure
– allow exit with failure if errors (default: false) -
--node-modules <node-modules-path>
– custom path to node modules (the command to get the path to the node modulesnpm list -g | head -1
) -
-w --working-dir <working-dir>
– the working directory should be set if the project folder differs from the CWD. For example, when using the linter in vs code (the command to get the path to the working dirpwd
in the foliant project folder)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
-
-f
,--fix
– fix formatting errors with markdownlint (default: false) -
-m
,--markdownlintmode
– set mode for markdownlint. Possible values:full
– check md files with markdownlint and markdown-link-checkslim
(default value) – check for critical errors with markdownlinttypograph
– fix typograph errors with markdownlintmdlint-default
– check md files for critical formatting errors with markdownlint and validate external links with markdown-link-check
-
--includes-map
– set the path to the includes map (default: false) -
--foliant-config
– set the configuration file is a foliant from which chapters (default:./foliant.yml
)
-
-
markdown
– check md files for errors with markdownlint-v
,-s
,-c
,-d
,-a
,-l
,-f
,-m
,--includes-map
,--foliant-config
-
urls
validate external links with markdown-link-check-v
,-s
,-d
,-a
,-l
-
print
print linting results-v
-
create-config
create markdownlint config for styleguide adherence-v
,-s
,-p
,-d
,-m
.markdownlintignore
– an exception file, each line of which can contain a glob.
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