# @devrelkit/remark-include-code 中文文档

规范地址：https://npmcn.com/package/%40devrelkit/remark-include-code/

版本：0\.1\.2
npm 元数据更新时间：2026-05-21T20:39:01.869Z
中文译文更新时间：2026-11-12T04:07:06.505Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：76.2 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- peer 依赖：unified ^11\.0\.0
- 首次发布：2026-05-01T10:11:58.526Z
- 最新版本发布：2026-05-21T20:39:01.663Z
- 近 30 天下载量：9079（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

将外部文件的代码添加到markdown/MDX的插件中,并带有区域切分和线高光通关.

## 安装

```sh
npm install @devrelkit/remark-include-code
```

也可以使用：`pnpm add @devrelkit/remark-include-code`、`yarn add @devrelkit/remark-include-code`、`bun add @devrelkit/remark-include-code`

## README

# @ devrelkit/remark- including-code (中文(简体) )

A 类 [评论](https://github.com/remarkjs/remark) 插件中包含从外部文件到markdown / MDX的代码,带有命名区域切分和线高光通关.

经典问题: 文档中的代码样本与现实脱节, 因为它们在文档中以纯文本的形式存在。 此插件允许您将示例保留为 **在 CI 中测试的真实源文件**,然后在建设时把它们转换成文档.

## 安装

```sh
pnpm add -D @devrelkit/remark-include-code
# or
npm install --save-dev @devrelkit/remark-include-code
```

## 使用量

```js
import { remark } from "remark";
import remarkIncludeCode from "@devrelkit/remark-include-code";

const file = await remark()
  .use(remarkIncludeCode, {
    /* options */
  })
  .process(markdown);
```

在下调 / MDX 中,将内置代码替换为 `file=` 关于围栏的指令:

````md
```ts file=./examples/create-account.ts#region=create
```
````

插件读取 `./examples/create-account.ts` (与平分文件有关) `create` 区域,并替换代码块正文。 栅栏保持了语言标记,因此下游亮点正常工作.

### 区域标记

源文件中的区域使用在大多数语言中中立的评论样式:

```ts
// #region create
const account = createAccount({ payer, lamports });
// #endregion create
```

```python
# #region create
account = Account(payer=payer, lamports=1_000_000)
# #endregion create
```

插件选择注释符号( I)`//` 或者说 `#`)自动基于代码块的语言标记.

框外支持的语言 :

-   `//` - ts, tsx,打字机, js, js, jsx, javascript, 生锈, rs, c, cpp, go, java, s迅速, kotlin, scala, dart
-   `#` - py, python, s, bash, zsh, 红宝石, yaml, toml, r, perl

在一个文件中同名的多个区域被拼接(以空白行分隔)——用于将非相接的片段缝入一例.

区域中常见的领先缩进被剥去,所以一个缩入块内所定义的区域仍然会使冲出左出.

### 线条突出显示

添加 `highlight=` 以标记线条进行视觉强调:

````md
```ts file=./examples/create-account.ts#region=create highlight=2-5,10
```
````

默认情况下,区域被附加到编码块元中,作为 `{2-5,10}`,这就是 **志纪**, (中文(简体) ), **rehype - pretty - 代码**, (中文(简体) ), **虚拟新闻**,以及 **天体星光**配置 `highlightStyle` 用于其他渲染器(见选项).

### 整个文件包括:

放下枪 `#region=...` 包含整个文件:

````md
```ts file=./examples/full-script.ts
```
````

### 其他元字段经过

其它任何东西 `file=` 财务报告和审定财务报表 `highlight=` 保存在元字符串上 :

````md
```ts title="Kit" file=./examples/foo.ts#region=create
```
````

• 产出保留 `title="Kit"` 像CodeHike那样的渲染器 `<CodeTabs>` 看看他们期待什么.

## 选项

```ts
interface PluginOptions {
  rootDir?: string;
  highlightStyle?:
    | "fence-meta"
    | "codehike"
    | ((ctx: HighlightContext) => HighlightResult);
}
```

### `rootDir`

分辨率根用于 `file=` 路径。 默认正在处理的标记下文件的目录(建议) 。 如果您想要将实例集中到一个位置, 并用同一相对路径从任何地方引用它们, 请设置此选项 .

### `highlightStyle`

怎么样 `highlight=` 输出中的土地范围 :

-   **`"fence-meta"`** (默认):附件 `{2-5,10}` 到代码块元字符串。 与Shiki相容,rehype-pretty-code,VitePress,Astro Starlight,以及大多数现代的标记下亮相相相容.
-   **`"codehike"`**: 注射数 `// !mark(N:M)` (或 `# !mark(N:M)` 为散列语(hash-comment languages),位于每个突出显示范围以上,所以 [代码](https://codehike.org/)标记的注解处理器来取取.
-   **函数**:接收切片+范围+lang+元,返回最终代码+元. 将此用于任何其他渲染器或自定义注释格式.

```ts
import remarkIncludeCode, { type HighlightContext } from "@devrelkit/remark-include-code";

remark().use(remarkIncludeCode, {
  highlightStyle: (ctx: HighlightContext) => ({
    code: ctx.code,
    meta: `${ctx.meta} data-lines=${JSON.stringify(ctx.ranges)}`,
  }),
});
```

## 错误

当 :

-   `file=` 路径不能解析到可读文件
-   `#region=...` 源头不存在
-   `highlight=` 区域结构不正确 (`abc`, (中文(简体) ), `5-2`页:1

全部围成 `IncludeError` 包含 markdown 文件路径, 所以创建失败将您指向已损坏的文档 .

## 为什么是评论插件?

[`remark`](https://github.com/remarkjs/remark) 减值的一半 [`unified`](https://unifiedjs.com/) 生态系统。 它将标记分解为 AST(`mdast`),运行插件来转换那棵树,然后串行回放. MDX, Fumadocs, Docusaurus, Next.js, Astro, 以及大多数现代的标记下堆栈都在上面作曲—— 所以一个插件插件插槽通过一行连接到它们中 `.use(...)` 登记.

## 许可证

麻省理工学院

## 常见问题

### @devrelkit/remark-include-code 是什么？

将外部文件的代码添加到markdown/MDX的插件中,并带有区域切分和线高光通关\.

### 如何安装 @devrelkit/remark-include-code？

在项目目录运行 npm install @devrelkit/remark-include-code，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：unified（^11\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @devrelkit/remark-include-code 支持 TypeScript 吗？

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

### @devrelkit/remark-include-code 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @devrelkit/remark-include-code 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @devrelkit/remark-include-code 可以商用吗？

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

### @devrelkit/remark-include-code 的下载量有多少？

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

### @devrelkit/remark-include-code 还在维护吗？

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