Markdownlint Foliant rules

Custom markdownlint rules for Foliant-projects.

Rules

indented-fence

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.

non-literal-fence-label

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.

fenced-code-in-quote

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.

typograph

Checks for typographical errors.

Fixable: Most violations can be fixed by tooling

This rule is triggered when one of the following cases is detected.

Hyphen instead of dash

Example

physics - science

Corrected example:

physics – science

Dash instead of hyphen

Example:

semi–final

Corrected example:

semi-final

Rationale: Violations of this rule can lead to an improperly typed text.

validate-internal-links

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.

frontmatter-tags-exist

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
---

Configuration

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.

Install

Locate your Foliant-project directory

cd my-awesome-foliant-project

Install markdownlint-rules-foliant from npm

npm i markdownlint-rules-foliant

Usage

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.

Fixing errors

Run markdownlint-cli2-fix for all markdown files in src directory and check changed files

npx markdownlint-cli2-fix "src/**/*.md"

Visual Studio Code integration

Install the markdownlint extension for better interactive linting.

Tests

To run the tests, run:

npx ava