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.,termplugin) - 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.
:::
YFM025 - Missing local link anchor
Alias: missing-local-anchor
Diplodoc CLI, the documentation builder, reports this diagnostic during HTML builds when a local link points to an existing page but its fragment does not match an anchor on that page. It checks same-page links (#section) and links to other project pages (guide.md#section), using rendered automatic and explicit anchors, including anchors from included files.
For example, [Section](guide.md#installation) produces YFM025 if guide.md is reachable but has no installation anchor. Correct the link fragment or add the anchor to the target page. Missing or unreachable target pages produce YFM003 instead.
The default level is warn, independently of YFM002. Configure the rule in the CLI project's .yfmlint file:
log-levels:
YFM025: error # warn to report a warning, disabled to disable the check
For the data flow and the responsibilities of the builder, plugins, and lint rules, see Where checks run.