# @diplodoc/yfmlint 中文文档

规范地址：https://npmcn.com/package/%40diplodoc/yfmlint/

版本：1\.11\.2
npm 元数据更新时间：2026-10-30T14:08:37.912Z
中文译文更新时间：2026-11-13T04:39:33.116Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40diplodoc/yfmlint
原文对照：https://npmcn.com/package/%40diplodoc/yfmlint/?lang=original
项目主页：https://github.com/diplodoc-platform/yfmlint#readme
源码仓库：https://github.com/diplodoc-platform/yfmlint

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.3 MB，28 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-03-11T01:36:51.114Z
- 最新版本发布：2026-10-30T14:08:37.528Z
- 近 30 天下载量：2310（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 27 个）

## 中文简介

YFM (Yandex Flavored Markdown) 语法 linter 为 Diplodoc 平台设置自定义规则

## 安装

```sh
npm install @diplodoc/yfmlint
```

也可以使用：`pnpm add @diplodoc/yfmlint`、`yarn add @diplodoc/yfmlint`、`bun add @diplodoc/yfmlint`

## README

**英语** | [русский](https://github.com/diplodoc-platform/yfmlint/blob/master/README.ru.md)

* * *

[![NPM version](https://img.shields.io/npm/v/@diplodoc/yfmlint.svg?style=flat)](https://www.npmjs.org/package/@diplodoc/yfmlint) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_yfmlint&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_yfmlint) [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_yfmlint&metric=coverage)](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_yfmlint) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_yfmlint&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_yfmlint) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_yfmlint&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_yfmlint) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=diplodoc-platform_yfmlint&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=diplodoc-platform_yfmlint)

# YFM 语法 linter

YFM (Yandex Flavored Markdown) 语法 linter 为 Diplodoc 平台设置自定义规则. 扩展 [马克倒挂](https://github.com/DavidAnson/markdownlint) 带有YFM特定验证规则.

## 特征

-   **自定义 YFM 规则** 用于验证 YFM 特定语法
-   **与 Markdownlint 合并** - 所有标准平分规则都可用
-   **插件支持** - 与插件从 `@diplodoc/transform` (例如, `term` 插件( 插件)
-   **可配置规则级别** - 错误、警告、信息或已禁用
-   **源地图支持** - 液体模板处理后准确报告错误

## 安装

```bash
npm install @diplodoc/yfmlint
```

## 使用量

### 基本示例

```javascript
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);
}
```

### 带有插件

```javascript
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
  },
});
```

### 配置

规则可以配置不同的日志级别 :

```javascript
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
  },
};
```

## 文档

关于建筑、发展和贡献的详情,见 [一般事务人员(其他职等)](https://npmcn.com/package/%40diplodoc/yfmlint/AGENTS.md)。 。 。 .

## YFM 规则

这个软件包以自定义规则来扩展markdownlint用于YFM语法验证. 所有标准 [马克倒挂规则](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md) 也可查阅.

### YFM001 - 内含码行长度

**标记 :** `line_length`  
**别名 :** `inline-code-length`  
**参数:** `maximum` (默认:100)

验证内含代码跨度不超过最大长度. 用于防止超长的内置代码中断格式化 .

**示例**

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

### YFM002 - 没有找到链接头

**标记 :** `links`  
**别名 :** `no-header-found-for-link`

验证链接到目标文件中已存在的信头( 锁定) .

**示例**

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

### YFM003 - 无法连接

**标记 :** `links`  
**别名 :** `unreachable-link`

验证链接文件的存在和可访问性 。 检查 :

-   找不到文件
-   目录中缺少的文件
-   两项条件

**示例**

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

### YFM004 - 未关闭的表格

**标记 :** `table`  
**别名 :** `table-not-closed`

验证 YFM 表格是否正确关闭 。 要求 `table` 插件从 `@diplodoc/transform`。 。 。 .

### YFM005 - 标签列表未关闭

**标记 :** `tab`  
**别名 :** `tab-list-not-closed`

验证 YFM 标签列表是否正确关闭 。 要求 `tabs` 插件从 `@diplodoc/transform`。 。 。 .

### YFM006 - 术语定义重复

**标记 :** `term`  
**别名 :** `term-definition-duplicated`

验证术语定义不重复。 要求 `term` 插件从 `@diplodoc/transform`。 。 。 .

**示例**

```markdown
[term]: definition

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

### YFM007 - 无定义使用术语

**标记 :** `term`  
**别名 :** `term-used-without-definition`

验证所有使用过的术语都有相应的定义. 要求 `term` 插件从 `@diplodoc/transform`。 。 。 .

**示例**

```markdown
This uses [term] but no definition is provided.
```

### YFM008 - 内定义不允许的术语

**标记 :** `term`  
**别名 :** `term-inside-definition-not-allowed`

验证术语定义并不包含其他术语. 要求 `term` 插件从 `@diplodoc/transform`。 。 。 .

### YFM009 - 文件结尾处没有术语定义

**标记 :** `term`  
**别名 :** `no-term-definition-in-content`

验证所有术语定义都放在文件末尾。 要求 `term` 插件从 `@diplodoc/transform`。 。 。 .

**示例**

```markdown
[term]: definition

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

[another-term]: another definition
```

### YFM010 - 无法获取自动标题主播

**标记 :** `titles`  
**别名 :** `unreachable-autotitle-anchor`

验证链接到自动标题主机的链接 .

**示例**

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

### YFM011 - 最大 SVG 大小

**标记 :** `image_svg` **别名 :** `max-svg-size`

验证SVG图像不超过最大尺寸限制. 需要图像处理插件 `@diplodoc/transform`。 。 。 .

### YFM021 - 空自动向导锚

**标记 :** `titles` **别名 :** `empty-auto-heading-anchor`

检测锁定插件所用的标题 `@diplodoc/transform` 无法生成非空自动锚。 该规则被报告为默认警告. 添加一个明确的锚使标题可以地址 .

锁定插件必须传递到 `yfmlint()` 为了这个规则的工作。 Diplodoc CLI和VS代码扩展已经提供了它.

**无效 :**

```markdown
## 😀
```

**修补 :**

```markdown
## 😀 {#emoji-section}
```

### YFM024 - 空的快手标题锚

**标记 :** `titles` **别名 :** `empty-custom-heading-anchor`

当最终标题属性块中的快手ID为空时警告, 例如 `{# section-id}` 或者说 `{#}`。其它处类似属性的文本不警告. 使用 `{#section-id}` 换句话说 有效条目周围的空格( E)`{ #section-id }`, (中文(简体) ), 分类、引用值和任意布尔属性得到支持. 譬如说, `{#id hidden}`, (中文(简体) ), `{#id data-x}` 财务报告和审定财务报表 `{#id custom-flag}` 你不要警告我. ID 之后的空字被解析为布尔属性;规则不猜测 作者是否打算使用多词ID或去除这些属性.

默认关卡是 **战争**,而不是错误;警告本身不会失败. 它可以通过通常的线粒体配置被禁用或被推广.

渲染倒回了自动锚,以进行空解析的ID. 需要锁定插件 `@diplodoc/transform` **4.78.6 或稍后时间**。 。 。 . 将此插件传递给 `yfmlint()` 发送 `YFM024` 符号标记. 没有此标记的旧插件继续工作, 但无法发出此警告 .

### YFM023 - 无效的能见度受众

**标记 :** `directives` **别名 :** `invalid-visibility-audience`

验证 `visibility` 块选择一个被支持的听众。 规矩是 默认报告为错误,所以一个类型不能默默地隐藏已发布的内容.

**有效性 :**

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

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

**无效 :**

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

### YFM025 - 缺少本地链接主锚

**别名:** `missing-local-anchor`

[Diplodoc CLI 语录](https://github.com/diplodoc-platform/cli#local-anchor-diagnostics),文档构建器,当本地链接指向已存在的页面时,在HTML构建过程中报告这种诊断,但其片段与该页面上的主锚不符. 它检查同页链接(`#section`)和链接到其他项目网页(`guide.md#section`),使用已实现的自动和明确的锚,包括从所包含文件中被锁定.

譬如说, `[Section](guide.md#installation)` 生产 `YFM025` 若为 `guide.md` 可达但无 `installation` 锚. 校正链接片段或将主机添加到目标页面中 。 缺少或无法访问的目标页面 `YFM003` 换句话说.

默认关卡是 `warn`,独立于 `YFM002`配置 CLI 项目的规则 `.yfmlint` 文件 :

```yaml
log-levels:
  YFM025: error # warn to report a warning, disabled to disable the check
```

关于数据流和构建者的责任,插件,和林特规则,参见 [检查运行的地方](https://diplodoc.com/docs/en/project/lint#check-implementation)。 。 。 .

## 常见问题

### @diplodoc/yfmlint 是什么？

YFM \(Yandex Flavored Markdown\) 语法 linter 为 Diplodoc 平台设置自定义规则

### 如何安装 @diplodoc/yfmlint？

在项目目录运行 npm install @diplodoc/yfmlint，或使用 pnpm add / yarn add / bun add。

### @diplodoc/yfmlint 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @diplodoc/yfmlint 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @diplodoc/yfmlint 可以商用吗？

@diplodoc/yfmlint 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @diplodoc/yfmlint 的下载量有多少？

根据 npm 官方下载统计，@diplodoc/yfmlint 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,310 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @diplodoc/yfmlint 还在维护吗？

最新版本 1\.11\.2 发布于 2026/10/30（14 天前）；至今共发布 38 个版本，其中过去 12 个月发布了 27 个；首次发布于 2025/03/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。