Custom markdownlint
rules
for Foliant-projects.
Fenced code block should be indented by 4 spaces at least.
This rule is triggered when there are fenced code blocks indented by 1 to 3 spaces.
Example:
```bash
fenced code block [indented by 3 spaces]
```
Correct example:
```bash
fenced code block [indented by 0 spaces]
```
Rationale: Violations of this rule can lead to improperly rendered content.
The Language label of fenced code block shouldn't contain non-literal symbols.
This rule is triggered when there are fenced code blocks with a label containing non-literal symbols.
Example:
```json{
"name": "markdownlint-rules-foliant",
"version": "0.0.1",
"description": "Markdownlint rules for Foliant projects",
"license": "MIT"
}
```
Correct example:
```json
{
"name": "markdownlint-rules-foliant",
"version": "0.0.1",
"description": "Markdownlint rules for Foliant projects",
"license": "MIT"
}
```
Rationale: Violations of this rule can lead to improperly rendered content.
Quotes shouldn't contain fenced code blocks.
This rule is triggered when there are fenced code blocks indented by 0 to 4 spaces from quote sign >
.
Example:
> ```python
> import print
> print("backtick fenced code block with lang label")
> ```
Correct example:
> ```python
> import print
> print("backtick fenced code block with lang label")
> ```
Rationale: Violations of this rule can lead to improperly rendered content.
Checks for typographical errors.
Fixable: Most violations can be fixed by tooling
This rule is triggered when one of the following cases is detected.
Example
physics - science
Corrected example:
physics – science
Example:
semi–final
Corrected example:
semi-final
Rationale: Violations of this rule can lead to an improperly typed text.
Validates local links according to a common foliant-project structure.
Parameters: src, project
This rule is triggered when a local link without a proper reference is found.
Checks if there are tags in the frontmatter. Supported frontmatter formats: XML, YAML, and JSON.
Fixable: The none
tag will be added into frontmatter.
If there is no front matter, a fronmatter in YAML format with the tag none
will be added:
---
tags: none
---
validate-internal-links takes two optional arguments. You can specify the source directory and name of the project. It can be useful in case of linting inside a docker-container.
{
"customRules": [
"validate-internal-links"
],
"config": {
"validate-internal-links": {
"src": "./src",
"project": "markdownlint-foliant-rules"
}
}
}
Rationale: Violations of this rule can lead to broken links.
Locate your Foliant-project directory
cd my-awesome-foliant-project
Install markdownlint-rules-foliant from npm
npm i markdownlint-rules-foliant
Create config file .markdownlint-cli2.jsonc
for markdownlint-cli2 in the project root
{
"customRules": [
"markdownlint-rules-foliant/lib/indented-fence",
"markdownlint-rules-foliant/lib/non-literal-fence-label",
"markdownlint-rules-foliant/lib/fenced-code-in-quote",
"markdownlint-rules-foliant/lib/typograph",
"markdownlint-rules-foliant/lib/validate-internal-links"
],
"config": {
"default": false,
"indented-fence": true,
"non-literal-fence-label": true,
"fenced-code-in-quote": true,
"typograph": true,
"validate-internal-links": true
}
}
Run markdownlint-cli2 for all markdown files in src
directory and check results
$ npx markdownlint-cli2 "src/**/*.md"
markdownlint-cli2 v0.4.0 (markdownlint v0.25.1)
Finding: test/test-src/**/*.md
Linting: 9 file(s)
Summary: 5 error(s)
src/fenced-code-in-quote.md:3 fenced-code-in-quote Fenced code shouldn't be in quote
src/indented-fence.md:8 indented-fence Fenced code shouldn't be indented by 1 to 3 spaces [Context: " ```python"]
src/non-literal-fence-label.md:3 non-literal-fence-label Invalid language label in fenced code block
src/topic-A/validate-internal-links.md:39 validate-internal-links Broken link [file does not exist] [Context: "adjacent-document"]
src/typograph.md:9:5 typograph typograph error [dash instead of hyphen]
npx is needed if markdownlint-cli2 is not installed globally. Otherwise, you may run markdownlint-cli2 without additional tools.
Run markdownlint-cli2-fix for all markdown files in src
directory and check changed files
npx markdownlint-cli2-fix "src/**/*.md"
Install the markdownlint extension for better interactive linting.
To run the tests, run:
npx ava