@mdit/plugin-field

支持创建块级自定义字段容器的插件。

使用

import MarkdownIt from "markdown-it";
import { field } from "@mdit/plugin-field";

const mdIt = new MarkdownIt().use(field, {
  // 你的选项
});

mdIt.render(`
::: fields
@\`prop1\` type="string" required
Description 1
:::
`);

语法

容器

你可以使用 ::: fields 和 ::: 创建字段容器。默认名称为 fields，你可以通过 name 选项进行自定义。

你还可以使用 ::: fields #id 为容器提供 ID。

项目

在容器内部，以 @ 开头并紧接行内代码的行是字段项目。你可以在闭合的反引号后添加属性。

::: fields
@`prop1` type="string" required
项目 1 描述
:::

在标记之后、容器关闭标记之前或同级的下一个标记之前的任何内容都将被视为字段内容。

名称

名称是行内代码，完全遵循 Markdown 的行内代码语法：

@`locales.<localePath>.latestUpdateAt` type=string
@`config[*].matches[*]` type=`RegExp`

名称必须在同一行内闭合，否则该行不是字段项目。

模板字符串

在 JavaScript 模板字符串中书写时（如上面的 mdIt.render 例子），反引号需要转义：

@\`prop1\`

属性

属性是以 = 分隔的键值对。值可以使用引号，也可以不用。

@`prop1` type="string" required default="value"

对于不带引号的值，值将在第一个空格或空白处结束。
值可以使用 "、' 或 ` 包裹。
被 " 或 ' 包裹的值中的反斜杠遵循 Markdown 的转义规则：标点前的反斜杠会被移除，其余反斜杠原样保留。因此 default="^\d+$" 和 default="C:\new" 会保留反斜杠，而 default="hello \"world\"" 会得到 hello "world"。不带引号的值会被视作字面量。由于反斜杠也会转义引号本身，想以反斜杠结尾请写成 default="C:\\"。
如果一个属性存在但没有 =，它将被视为布尔属性，值为 true。

反引号值

反引号值是行内代码，完全遵循 Markdown 的行内代码语法：

@`prop1` default=`['a', 'b']`

使用 " 或 ' 包裹的值仍会被其他工具按 Markdown 解析，其中 [a][b] 之类的写法可能被 linter 报为未定义的引用；反引号值对这些工具来说是行内代码，从而避免该问题。

未被反引号闭合的值会回退为不带引号的值，且该值以起始反引号开头。

允许的属性

默认情况下，所有属性都是允许的并按原样显示。你可以使用 allowedAttributes 选项来限制和自定义属性显示。

如果提供了 allowedAttributes：

只有数组中定义的属性会被显示。
属性将按照在数组中出现的顺序进行显示。
你可以为每个属性提供自定义的 name，以更改其在页眉中的标签。
你可以将属性标记为 boolean，以将其始终视为标志（忽略其任何值）。

field(md, {
  allowedAttributes: [
    { attr: "type", name: "属性类型" },
    { attr: "required", boolean: true },
  ],
});

嵌套

相同或不同的容器可以嵌套在项目内，缩进级别可以是相同的，也可以是部分缩进（小于代码块缩进级别，默认为4个空格）。

:::: fields
@`option`
父级描述。
::: props
@`prop1` type="string"
键描述。
@`prop2` type="number"
键描述。
:::
@`option2`
另一个父级描述。
::::

为了在另一个字段内创建字段项目，每个嵌套级别将起始 @ 增加一个：

::: fields
@`prop1`
父级描述。
@@`prop1.key1` type="string"
键描述。
@@`prop1.key2` type="number"
键描述。
@`prop2`
另一个父级描述。
:::

现在 prop1 有两个嵌套键 key1 和 key2，而 prop2 没有嵌套键。

虽然像 prettier 这样的常用工具不喜欢小于4个空格的缩进，但插件设计为只要缩进小于代码块缩进（默认为4个空格）就可以灵活处理。这允许更自然的嵌套，而不需要严格的缩进要求。

<!-- prettier-ignore-start -->
::: fields
@`prop1`
  父级描述。

  @@`prop1.key1` type="string"
  键描述。

  @@`prop1.key2` type="number"
  键描述。
:::
<!-- prettier-ignore-end -->

转义

字段容器内以 @ 开头并紧接行内代码的行是字段项目。将 @ 用 \ 转义即可作为内容保留：

\@`not-a-field`

选项

name

类型：string
默认值："fields"
详情：字段容器名称。

classPrefix

类型：string
默认值："field-"
详情：生成的 CSS 类名前缀。

parseAttributes

类型：boolean
默认值：true
详情：是否解析字段标记后的 key="val" 属性。

allowedAttributes

类型：FieldAttr[]

interface FieldAttr {
  /**
   * 属性名
   */
  attr: string;

  /**
   * 属性的显示名称。如果未提供，将使用 `attr` 作为显示名称，首字母大写。
   */
  name?: string;

  /**
   * 布尔属性，任何属性存在都将被视为 true，值将被忽略。
   *
   * @default false
   */
  boolean?: boolean;
}

详情：允许的字段属性。如果不提供，所有属性都将被允许并按原样显示。

fieldsOpenRenderer

类型：RendererRule

/**
 * @param tokens - List of tokens.
 * @param index - Current token index.
 * @param options - Markdown-it options.
 * @param env - Markdown-it environment.
 * @param self - Markdown-it renderer instance.
 *
 * @returns Rendered HTML string.
 */
type RendererRule = (
  tokens: Token[],
  index: number,
  options: Required<MarkdownItOptions>,
  env: Env | undefined,
  self: Renderer,
) => string;

详情：字段容器打开渲染函数。

fieldsCloseRenderer

类型：RendererRule

/**
 * @param tokens - List of tokens.
 * @param index - Current token index.
 * @param options - Markdown-it options.
 * @param env - Markdown-it environment.
 * @param self - Markdown-it renderer instance.
 *
 * @returns Rendered HTML string.
 */
type RendererRule = (
  tokens: Token[],
  index: number,
  options: Required<MarkdownItOptions>,
  env: Env | undefined,
  self: Renderer,
) => string;

详情：字段容器关闭渲染函数。

fieldOpenRenderer

类型：MarkdownItFieldOpenRenderer

type FieldAttrQuote = "none" | "single" | "double" | "backtick";

interface FieldAttrItem {
  /**
   * 属性名
   */
  attr: string;

  /**
   * 属性显示名称
   */
  name: string;

  /**
   * 属性值
   */
  value: string | true;

  /**
   * 源码中使用的引号类型
   */
  quote: FieldAttrQuote;
}

interface FieldMeta {
  /**
   * 字段名称
   */
  name: string;

  /**
   * 字段级别，从 1 开始
   */
  level: number;

  /**
   * 排序后的字段属性
   */
  attributes: FieldAttrItem[];
}

type MarkdownItFieldOpenRenderer = (
  meta: FieldMeta,
  tokens: Token[],
  index: number,
  options: Required<MarkdownItOptions>,
  env: Env | undefined,
  self: Renderer,
) => string;

详情：字段项打开渲染函数。

fieldCloseRenderer

类型：RendererRule

/**
 * @param tokens - List of tokens.
 * @param index - Current token index.
 * @param options - Markdown-it options.
 * @param env - Markdown-it environment.
 * @param self - Markdown-it renderer instance.
 *
 * @returns Rendered HTML string.
 */
type RendererRule = (
  tokens: Token[],
  index: number,
  options: Required<MarkdownItOptions>,
  env: Env | undefined,
  self: Renderer,
) => string;

详情：字段项关闭渲染函数。

演示

prop1: Type: stringRequired
项目 1 描述
prop2: Type: number
项目 2 描述

基础字段

::: fields
@`prop1` type="string" required
项目 1 描述

@`prop2` type="number"
项目 2 描述
:::

parent

父级项目描述。

child: 子级项目描述。

嵌套字段

::: fields
@`parent`
父级项目描述。

@@`child`
子级项目描述。
:::

import MarkdownIt from "markdown-it";
import { field } from "@mdit/plugin-field";

const mdIt = new MarkdownIt().use(field, {
  name: "props",
  allowedAttributes: [
    { attr: "type", name: "属性类型" },
    { attr: "required", boolean: true },
  ],
});

prop1: Property Type: stringRequired
这是一个必填的字符串属性。
prop2: Property Type: number
这是一个数字属性。

自定义名称和属性

```ts
import MarkdownIt from "markdown-it";
import { field } from "@mdit/plugin-field";

const mdIt = new MarkdownIt().use(field, {
  name: "props",
  allowedAttributes: [
    { attr: "type", name: "属性类型" },
    { attr: "required", boolean: true },
  ],
});
```

::: props
@`prop1` type="string" required
这是一个必填的字符串属性。

@`prop2` type="number"
这是一个数字属性。
:::