english | русский

YFM syntax linter

YFM (Yandex Flavored Markdown) syntax linter with custom rules for Diplodoc platform. Extends markdownlint with YFM-specific validation rules.

Features

• Custom YFM rules for validating YFM-specific syntax
• Integration with markdownlint - all standard markdownlint rules are available
• Plugin support - integrates with plugins from @diplodoc/transform (e.g., term plugin)
• Configurable rule levels - error, warn, info, or disabled
• Source map support - accurate error reporting after Liquid template processing

Installation

npm install @diplodoc/yfmlint

Usage

Basic Example

import {yfmlint, log, LogLevels} from '@diplodoc/yfmlint';

const content = `# Title

[Link to missing file](./missing.md)
`;

const errors = await yfmlint(content, 'example.md', {
  lintConfig: {
    YFM003: LogLevels.ERROR, // Unreachable link
  },
});

if (errors && errors.length > 0) {
  log(errors, console);
}

With Plugins

import {yfmlint} from '@diplodoc/yfmlint';
import termPlugin from '@diplodoc/transform/plugins/term';

const errors = await yfmlint(content, path, {
  plugins: [termPlugin],
  pluginOptions: {
    // Plugin-specific options
  },
  lintConfig: {
    YFM007: true, // Term used without definition
    YFM009: 'warn', // Term definition not at end of file
  },
});

Configuration

Rules can be configured with different log levels:

const lintConfig = {
  // Boolean: true = warn, false = disabled
  YFM001: true,
  YFM002: false,

  // String: log level name
  YFM003: 'error',
  YFM004: 'warn',
  YFM005: 'info',

  // Object: full configuration
  YFM001: {
    level: 'warn',
    maximum: 120, // Custom parameter
  },
};

Documentation

For detailed information about architecture, development, and contributing, see AGENTS.md.

YFM Rules

This package extends markdownlint with custom rules for YFM syntax validation. All standard markdownlint rules are also available.

YFM001 - Inline code line length

Tags: line_length
Aliases: inline-code-length
Parameters: maximum (default: 100)

Validates that inline code spans don't exceed the maximum length. Useful for preventing overly long inline code that breaks formatting.

Example:

`this is a very long inline code that exceeds the maximum length and will trigger YFM001`

YFM002 - No header found for link

Tags: links
Aliases: no-header-found-for-link

Validates that links to headers (anchors) reference existing headers in the target file.

Example:

[Link to non-existent header](./file.md#nonexistent)

YFM003 - Unreachable link

Tags: links
Aliases: unreachable-link

Validates that linked files exist and are accessible. Checks for:

• File not found
• File missing in table of contents
• Both conditions

Example:

[Link to missing file](./missing.md)

YFM004 - Table not closed

Tags: table
Aliases: table-not-closed

Validates that YFM tables are properly closed. Requires the table plugin from @diplodoc/transform.

YFM005 - Tab list not closed

Tags: tab
Aliases: tab-list-not-closed

Validates that YFM tab lists are properly closed. Requires the tabs plugin from @diplodoc/transform.

YFM006 - Term definition duplicated

Tags: term
Aliases: term-definition-duplicated

Validates that term definitions are not duplicated. Requires the term plugin from @diplodoc/transform.

Example:

[term]: definition

[term]: another definition <!-- Error: duplicate definition -->

YFM007 - Term used without definition

Tags: term
Aliases: term-used-without-definition

Validates that all used terms have corresponding definitions. Requires the term plugin from @diplodoc/transform.

Example:

This uses [term] but no definition is provided.

YFM008 - Term inside definition not allowed

Tags: term
Aliases: term-inside-definition-not-allowed

Validates that term definitions don't contain other terms. Requires the term plugin from @diplodoc/transform.

YFM009 - Term definition not at end of file

Tags: term
Aliases: no-term-definition-in-content

Validates that all term definitions are placed at the end of the file. Requires the term plugin from @diplodoc/transform.

Example:

[term]: definition

Some content here <!-- Error: content after term definitions -->

[another-term]: another definition

YFM010 - Unreachable autotitle anchor

Tags: titles
Aliases: unreachable-autotitle-anchor

Validates that links to autotitle anchors reference existing titles.

Example:

[Link to non-existent title](#nonexistent-title)

YFM011 - Max SVG size

Tags: image_svg Aliases: max-svg-size

Validates that SVG images don't exceed the maximum size limit. Requires image processing plugins from @diplodoc/transform.

YFM021 - Empty automatic heading anchor

Tags: titles Aliases: empty-auto-heading-anchor

Detects headings for which the anchors plugin from @diplodoc/transform cannot generate a non-empty automatic anchor. The rule is reported as a warning by default. Add an explicit anchor to make the heading addressable.

The anchors plugin must be passed to yfmlint() for this rule to work. Diplodoc CLI and the VS Code extension already provide it.

Invalid:

## 😀

Fix:

## 😀 {#emoji-section}

YFM024 - Empty shorthand heading anchor

Tags: titles Aliases: empty-custom-heading-anchor

Warns when the shorthand ID in the final heading attribute block is empty, such as {# section-id} or {#}. Attribute-like text elsewhere does not warn. Use {#section-id} instead. Spaces around a valid entry ({ #section-id }), classes, quoted values and arbitrary boolean attributes are supported. For example, {#id hidden}, {#id data-x} and {#id custom-flag} do not warn. Bare words after the ID are parsed as boolean attributes; the rule does not guess whether the author intended a multi-word ID or remove these attributes.

The default level is WARN, not ERROR; the warning does not itself fail a build. It can be disabled or promoted through the usual lint configuration.

Rendering falls back to the automatic anchor for an empty parsed ID. Requires the anchors plugin from @diplodoc/transform 4.78.6 or later. Pass this plugin to yfmlint() to emit the YFM024 token marker. Older plugins without this marker continue to work but cannot emit this warning.

YFM023 - Invalid visibility audience

Tags: directives Aliases: invalid-visibility-audience

Validates that every visibility block selects exactly one supported audience. The rule is reported as an error by default so a typo cannot silently hide published content.

Valid:

:::visibility human
Human-only content.
:::

:::visibility agent
Agent-only content.
:::

Invalid:

:::visibility agents
This block uses an unsupported plural value.
:::