@ devrelkit/remark- including-code (中文(简体) )
A 类 评论 插件中包含从外部文件到markdown / MDX的代码,带有命名区域切分和线高光通关.
经典问题: 文档中的代码样本与现实脱节, 因为它们在文档中以纯文本的形式存在。 此插件允许您将示例保留为 在 CI 中测试的真实源文件,然后在建设时把它们转换成文档.
安装
pnpm add -D @devrelkit/remark-include-code
# or
npm install --save-dev @devrelkit/remark-include-code
使用量
import { remark } from "remark";
import remarkIncludeCode from "@devrelkit/remark-include-code";
const file = await remark()
.use(remarkIncludeCode, {
/* options */
})
.process(markdown);
在下调 / MDX 中,将内置代码替换为 file= 关于围栏的指令:
```ts file=./examples/create-account.ts#region=create
```
插件读取 ./examples/create-account.ts (与平分文件有关) create 区域,并替换代码块正文。 栅栏保持了语言标记,因此下游亮点正常工作.
区域标记
源文件中的区域使用在大多数语言中中立的评论样式:
// #region create
const account = createAccount({ payer, lamports });
// #endregion create
# #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= 以标记线条进行视觉强调:
```ts file=./examples/create-account.ts#region=create highlight=2-5,10
```
默认情况下,区域被附加到编码块元中,作为 {2-5,10},这就是 志纪, (中文(简体) ), rehype - pretty - 代码, (中文(简体) ), 虚拟新闻,以及 天体星光配置 highlightStyle 用于其他渲染器(见选项).
整个文件包括:
放下枪 #region=... 包含整个文件:
```ts file=./examples/full-script.ts
```
其他元字段经过
其它任何东西 file= 财务报告和审定财务报表 highlight= 保存在元字符串上 :
```ts title="Kit" file=./examples/foo.ts#region=create
```
• 产出保留 title="Kit" 像CodeHike那样的渲染器 <CodeTabs> 看看他们期待什么.
选项
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),位于每个突出显示范围以上,所以 代码标记的注解处理器来取取.- 函数:接收切片+范围+lang+元,返回最终代码+元. 将此用于任何其他渲染器或自定义注释格式.
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 减值的一半 unified 生态系统。 它将标记分解为 AST(mdast),运行插件来转换那棵树,然后串行回放. MDX, Fumadocs, Docusaurus, Next.js, Astro, 以及大多数现代的标记下堆栈都在上面作曲—— 所以一个插件插件插槽通过一行连接到它们中 .use(...) 登记.
许可证
麻省理工学院