跳转到内容

Unified API 参考

Astro 通过 @astrojs/markdown-remark 包提供对流行 Markdown 生态系统 unified 的可选支持。借助 remark 和 rehype 插件,你可以自定义并扩展渲染过程。该包还提供了一组辅助函数和类型,可用于构建集成或插件。

有关功能和使用示例,请参阅 Markdown 指南中的 Markdown 处理器。

以下辅助函数从 @astrojs/markdown-remark 导入:

import {
createMarkdownProcessor,
isUnifiedProcessor,
parseFrontmatter,
rehypeHeadingIds,
unified,
} from "@astrojs/markdown-remark";

类型: (opts?: AstroMarkdownOptions) => Promise<MarkdownRenderer>

添加于: @astrojs/[email protected]

创建一个独立的、基于 unified 的 Markdown 渲染器。如果你需要脱离项目已配置的 markdown.processor 来渲染 Markdown,这会很有用。

src/utils/markdown.ts
import { createMarkdownProcessor } from "@astrojs/markdown-remark";
const processor = await createMarkdownProcessor();
const { code, metadata } = await processor.render("# Hello world");

类型: (p: { name: string; }) => boolean

添加于: @astrojs/[email protected]

判断给定的 Markdown 处理器是否为 unified。如果你需要在应用 unified 专属逻辑之前检查处理器类型,这会很有用。

以下示例在集成中检查已配置的 Markdown 处理器是否为 unified:

src/integrations/my-integration.ts
import { isUnifiedProcessor } from "@astrojs/markdown-remark";
import type { AstroIntegration } from "astro";
export default function myIntegration(): AstroIntegration {
return {
name: "my-integration",
hooks: {
"astro:config:done": ({ config }) => {
if (isUnifiedProcessor(config.markdown.processor)) {
// Apply unified-specific logic here
}
},
},
};
}

类型: RehypePlugin

添加于: @astrojs/[email protected]

为 Markdown 内容中的所有标题生成并收集标题 ID。导入或渲染 Markdown 内容时,可以使用这些 ID。

有关用法示例,请参阅 Markdown 指南中的标题 ID 与插件。

类型: (options?: UnifiedProcessorOptions) => MarkdownProcessor

添加于: @astrojs/[email protected]

创建一个基于 unified 的处理器,用于渲染 .md 和 .mdx 文件。将它传递给 markdown.processor,即可将 unified 用作默认 Markdown 处理器。

请参阅 Markdown 指南,了解如何设置 Markdown 处理器以及使用 remark 和 rehype 插件。

类型: UnifiedProcessorOptions

你可以使用以下选项来自定义 unified 处理器的行为。

类型: RemarkPlugins
默认值: []

传递 remark 插件,以自定义 Markdown 的构建方式。你可以导入并应用插件函数(推荐),也可以将插件名作为字符串传递。

以下示例将带有自定义 heading 选项的 remark-toc 插件传递给 unified 处理器:

astro.config.mjs
import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import remarkToc from "remark-toc";
export default defineConfig({
markdown: {
processor: unified({
remarkPlugins: [[remarkToc, { heading: "contents" }]],
}),
},
});

类型: RehypePlugins
默认值: []

传递 rehype 插件,以自定义如何根据 Markdown 内容生成 HTML。你可以导入并应用插件函数(推荐),也可以将插件名作为字符串传递。

以下示例将 rehype-accessible-emojis 插件传递给 unified 处理器:

astro.config.mjs
import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import { rehypeAccessibleEmojis } from "rehype-accessible-emojis";
export default defineConfig({
markdown: {
processor: unified({
rehypePlugins: [rehypeAccessibleEmojis],
}),
},
});

类型: RemarkRehype

传递选项给 remark-rehype 插件,以控制 Markdown 转换为 HTML 的方式。

以下示例自定义脚注标签:

astro.config.mjs
import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
export default defineConfig({
markdown: {
processor: unified({
remarkRehype: {
footnoteLabel: "Footnotes",
footnoteBackLabel: "Back to reference 1",
},
}),
},
});

类型: PluggableList
默认值: []

传递 recma 插件,以自定义 MDX 文件的 ESTree 输出。这对于修改或注入 JavaScript 变量很有用。

astro.config.mjs
import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
import myRecmaPlugin from "./my-recma-plugin.mjs";
export default defineConfig({
markdown: {
processor: unified({
recmaPlugins: [myRecmaPlugin],
}),
},
});

你可以使用 AST Explorer 查看 ESTree 输出,也可以尝试使用 estree-util-visit 搜索 JavaScript 节点。

类型: boolean
默认值: true

是否启用 GitHub 风格 Markdown(GFM) 支持。

要禁用此功能,请将 gfm 选项设为 false:

astro.config.mjs
import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
export default defineConfig({
markdown: {
processor: unified({
gfm: false,
}),
},
});
了解如何在 Astro 中使用 GitHub 风格 Markdown。

类型: boolean | Smartypants
默认值: true

是否使用 SmartyPants 格式化器,将直引号转换为弯引号,将连字符转换为 en dash 或 em dash,并将三个句点转换为省略号。

你可以禁用此功能,也可以提供配置对象,并使用 retext-smartypants 支持的属性来自定义行为。

以下示例会禁用智能标点:

astro.config.mjs
import { defineConfig } from "astro/config";
import { unified } from "@astrojs/markdown-remark";
export default defineConfig({
markdown: {
processor: unified({
smartypants: false,
}),
},
});
请参阅 Markdown 指南,了解如何配置智能标点。

以下类型从 @astrojs/markdown-remark 导入:

import type {
AstroMarkdownOptions,
MarkdownHeading,
MarkdownProcessor,
MarkdownRenderOptions,
MarkdownRenderResult,
MarkdownRenderer,
RehypePlugin,
RehypePlugins,
RemarkPlugin,
RemarkPlugins,
RemarkRehype,
ShikiConfig,
Smartypants,
SyntaxHighlightConfig,
SyntaxHighlightConfigType,
} from "@astrojs/markdown-remark";

类型: { syntaxHighlight?: SyntaxHighlightConfig | SyntaxHighlightConfigType | false; shikiConfig?: ShikiConfig; image?: { domains?: string[]; remotePatterns?: RemotePattern[]; }; }

添加于: @astrojs/[email protected]

描述 Markdown 处理器的配置。除所有 markdown 选项外,还包含以下选项。

类型: { domains?: string[]; remotePatterns?: RemotePattern[]; }

指定 Markdown 处理器的图像配置。

类型: string[]

请参阅配置参考中的 image.domains。

类型: RemotePattern[]

请参阅配置参考中的 image.remotePatterns。

类型: { depth: number; slug: string; text: string; }

添加于: @astrojs/[email protected]

表示 Markdown 或 MDX 文档中的一个标题。

类型: number

标题级别,从 1(<h1>)到 6(<h6>)。

类型: string

指定生成的 slug,该值用作锚点链接的 id 属性。

类型: string

包含渲染后的标题文本内容。

类型: object

添加于: @astrojs/[email protected]

描述已配置的 markdown.processor。如果你想声明某个变量可以接受任意内置 Markdown 处理器,这会很有用。

类型: { fileURL?: URL; frontmatter?: Record<string, any>; }

添加于: @astrojs/[email protected]

描述渲染 Markdown 内容时可用的选项。

类型: URL

指定正在渲染的 Markdown 文件的 URL。

类型: Record<string, any>

提供 Markdown 内容的 frontmatter 数据。

类型: { code: string; metadata: { headings: MarkdownHeading[]; localImagePaths: string[]; remoteImagePaths: string[]; frontmatter: Record<string, any>; }; }

添加于: @astrojs/[email protected]

描述渲染后的 Markdown 文件。

类型: string

包含渲染后的 HTML 代码。

类型: { headings: MarkdownHeading[]; localImagePaths: string[]; remoteImagePaths: string[]; frontmatter: Record<string, any>; }

描述与内容关联的元数据。

类型: MarkdownHeading[]

提取出的标题列表。

MarkdownRenderResult.metadata.localImagePaths
Section titled “MarkdownRenderResult.metadata.localImagePaths”

类型: string[]

渲染内容中引用的本地图片路径数组。

MarkdownRenderResult.metadata.remoteImagePaths
Section titled “MarkdownRenderResult.metadata.remoteImagePaths”

类型: string[]

渲染内容中引用的远程图片路径数组。

类型: Record<string, any>

传递给渲染器的 frontmatter。

类型: { render: (content: string, opts?: MarkdownRenderOptions) => Promise<MarkdownRenderResult>; }

添加于: @astrojs/[email protected]

指定独立 Markdown 处理器所实现的接口。

类型: (content: string, opts?: MarkdownRenderOptions) => Promise<MarkdownRenderResult>

为给定的 Markdown 内容生成渲染后的 HTML 和元数据。你可以通过第二个参数中的选项自定义渲染过程。

类型: Plugin<PluginParameters, HastRoot>

添加于: @astrojs/[email protected]

定义 unified 生态系统中的 rehype 插件。

类型: (string | [string, any] | RehypePlugin | [RehypePlugin, any])[]

添加于: @astrojs/[email protected]

用于自定义 Markdown 内容生成的 HTML 输出的 rehype 插件列表。每一项可以是已导入的插件,也可以是 Astro 应自动导入的包名。

类型: Plugin<PluginParameters, MdastRoot>

添加于: @astrojs/[email protected]

定义 unified 生态系统中的 remark 插件。

类型: (string | [string, any] | RemarkPlugin | [RemarkPlugin, any])[]

添加于: @astrojs/[email protected]

用于自定义 Markdown 处理过程的 remark 插件列表。每一项可以是已导入的插件,也可以是 Astro 应自动导入的包名。

类型: Record<string, unknown>

添加于: @astrojs/[email protected]

指定传递给 remark-rehype 插件的选项。

类型: object

添加于: @astrojs/[email protected]

描述配置 Shiki 语法高亮器时使用的选项。

了解如何配置语法高亮并查看使用示例。

类型: LanguageRegistration[]

启用语法高亮的 Shiki 语言列表。

类型: Record<string, string>

定义将别名映射到 Shiki 语言 ID 的自定义规则。

有关更多信息,请参阅 Shiki 语言别名。

类型: ThemePresets | ThemeRegistration | ThemeRegistrationRaw

指定语法高亮的默认主题。你可以使用 Shiki 内置主题或自定义 Shiki 主题。

了解如何通过示例设置默认 Shiki 主题。

类型: Record<string, ThemePresets | ThemeRegistration | ThemeRegistrationRaw>

将主题名称映射到对应 Shiki 主题配置的对象。

了解如何通过示例设置深色和浅色主题。

类型: 'light' | 'dark' | string | false

指定定义了 [ShikiConfig.themes] 时要使用的默认主题。

类型: boolean | null

是否通过换行避免水平滚动。

类型: ShikiTransformer[]

自定义生成 HTML 的 Shiki 转换器列表。

如果只需对特定代码块应用转换器,请参阅如何将 transformers 应用于 <Code />。

类型: object

添加于: @astrojs/[email protected]

描述 retext-smartypants 的配置选项。

了解如何在 Astro 中使用智能标点。

类型: { type: SyntaxHighlightConfigType; excludeLangs?: string[]; }

添加于: @astrojs/[email protected]

指定已配置的语法高亮器以及要排除高亮的语言。

了解如何配置语法高亮并查看使用示例。

类型: 'shiki' | 'prism'

添加于: @astrojs/[email protected]

Astro 中支持的语法高亮器的联合类型。

贡献 社区 赞助