Unified API 参考
Astro 通过 @astrojs/markdown-remark 包提供对流行 Markdown 生态系统 unified 的可选支持。借助 remark 和 rehype 插件,你可以自定义并扩展渲染过程。该包还提供了一组辅助函数和类型,可用于构建集成或插件。
有关功能和使用示例,请参阅 Markdown 指南中的 Markdown 处理器。
从 @astrojs/markdown-remark 导入
Section titled “从 @astrojs/markdown-remark 导入”以下辅助函数从 @astrojs/markdown-remark 导入:
import { createMarkdownProcessor, isUnifiedProcessor, parseFrontmatter, rehypeHeadingIds, unified,} from "@astrojs/markdown-remark";createMarkdownProcessor()
Section titled “createMarkdownProcessor()”类型: (opts?: AstroMarkdownOptions) => Promise<MarkdownRenderer>
@astrojs/[email protected]
创建一个独立的、基于 unified 的 Markdown 渲染器。如果你需要脱离项目已配置的 markdown.processor 来渲染 Markdown,这会很有用。
import { createMarkdownProcessor } from "@astrojs/markdown-remark";
const processor = await createMarkdownProcessor();const { code, metadata } = await processor.render("# Hello world");isUnifiedProcessor()
Section titled “isUnifiedProcessor()”类型: (p: { name: string; }) => boolean
@astrojs/[email protected]
判断给定的 Markdown 处理器是否为 unified。如果你需要在应用 unified 专属逻辑之前检查处理器类型,这会很有用。
以下示例在集成中检查已配置的 Markdown 处理器是否为 unified:
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 } }, }, };}rehypeHeadingIds()
Section titled “rehypeHeadingIds()”类型: RehypePlugin
@astrojs/[email protected]
为 Markdown 内容中的所有标题生成并收集标题 ID。导入或渲染 Markdown 内容时,可以使用这些 ID。
unified()
Section titled “unified()”类型: (options?: UnifiedProcessorOptions) => MarkdownProcessor
@astrojs/[email protected]
创建一个基于 unified 的处理器,用于渲染 .md 和 .mdx 文件。将它传递给 markdown.processor,即可将 unified 用作默认 Markdown 处理器。
类型: UnifiedProcessorOptions
你可以使用以下选项来自定义 unified 处理器的行为。
options.remarkPlugins
Section titled “options.remarkPlugins”类型: RemarkPlugins
默认值: []
传递 remark 插件,以自定义 Markdown 的构建方式。你可以导入并应用插件函数(推荐),也可以将插件名作为字符串传递。
以下示例将带有自定义 heading 选项的 remark-toc 插件传递给 unified 处理器:
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" }]], }), },});options.rehypePlugins
Section titled “options.rehypePlugins”类型: RehypePlugins
默认值: []
传递 rehype 插件,以自定义如何根据 Markdown 内容生成 HTML。你可以导入并应用插件函数(推荐),也可以将插件名作为字符串传递。
以下示例将 rehype-accessible-emojis 插件传递给 unified 处理器:
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], }), },});options.remarkRehype
Section titled “options.remarkRehype”类型: RemarkRehype
传递选项给 remark-rehype 插件,以控制 Markdown 转换为 HTML 的方式。
以下示例自定义脚注标签:
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", }, }), },});options.recmaPlugins
Section titled “options.recmaPlugins”类型: PluggableList
默认值: []
传递 recma 插件,以自定义 MDX 文件的 ESTree 输出。这对于修改或注入 JavaScript 变量很有用。
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 节点。
options.gfm
Section titled “options.gfm”类型: boolean
默认值: true
是否启用 GitHub 风格 Markdown(GFM) 支持。
要禁用此功能,请将 gfm 选项设为 false:
import { defineConfig } from "astro/config";import { unified } from "@astrojs/markdown-remark";
export default defineConfig({ markdown: { processor: unified({ gfm: false, }), },});options.smartypants
Section titled “options.smartypants”类型: boolean | Smartypants
默认值: true
是否使用 SmartyPants 格式化器,将直引号转换为弯引号,将连字符转换为 en dash 或 em dash,并将三个句点转换为省略号。
你可以禁用此功能,也可以提供配置对象,并使用 retext-smartypants 支持的属性来自定义行为。
以下示例会禁用智能标点:
import { defineConfig } from "astro/config";import { unified } from "@astrojs/markdown-remark";
export default defineConfig({ markdown: { processor: unified({ smartypants: false, }), },});@astrojs/markdown-remark 类型
Section titled “@astrojs/markdown-remark 类型”以下类型从 @astrojs/markdown-remark 导入:
import type { AstroMarkdownOptions, MarkdownHeading, MarkdownProcessor, MarkdownRenderOptions, MarkdownRenderResult, MarkdownRenderer, RehypePlugin, RehypePlugins, RemarkPlugin, RemarkPlugins, RemarkRehype, ShikiConfig, Smartypants, SyntaxHighlightConfig, SyntaxHighlightConfigType,} from "@astrojs/markdown-remark";AstroMarkdownOptions
Section titled “AstroMarkdownOptions”类型: { syntaxHighlight?: SyntaxHighlightConfig | SyntaxHighlightConfigType | false; shikiConfig?: ShikiConfig; image?: { domains?: string[]; remotePatterns?: RemotePattern[]; }; }
@astrojs/[email protected]
描述 Markdown 处理器的配置。除所有 markdown 选项外,还包含以下选项。
AstroMarkdownOptions.image
Section titled “AstroMarkdownOptions.image”类型: { domains?: string[]; remotePatterns?: RemotePattern[]; }
指定 Markdown 处理器的图像配置。
AstroMarkdownOptions.image.domains
Section titled “AstroMarkdownOptions.image.domains”类型: string[]
请参阅配置参考中的 image.domains。
AstroMarkdownOptions.image.remotePatterns
Section titled “AstroMarkdownOptions.image.remotePatterns”类型: RemotePattern[]
请参阅配置参考中的 image.remotePatterns。
MarkdownHeading
Section titled “MarkdownHeading”类型: { depth: number; slug: string; text: string; }
@astrojs/[email protected]
表示 Markdown 或 MDX 文档中的一个标题。
MarkdownHeading.depth
Section titled “MarkdownHeading.depth”类型: number
标题级别,从 1(<h1>)到 6(<h6>)。
MarkdownHeading.slug
Section titled “MarkdownHeading.slug”类型: string
指定生成的 slug,该值用作锚点链接的 id 属性。
MarkdownHeading.text
Section titled “MarkdownHeading.text”类型: string
包含渲染后的标题文本内容。
MarkdownProcessor
Section titled “MarkdownProcessor”类型: object
@astrojs/[email protected]
描述已配置的 markdown.processor。如果你想声明某个变量可以接受任意内置 Markdown 处理器,这会很有用。
MarkdownRenderOptions
Section titled “MarkdownRenderOptions”类型: { fileURL?: URL; frontmatter?: Record<string, any>; }
@astrojs/[email protected]
描述渲染 Markdown 内容时可用的选项。
MarkdownRenderOptions.fileURL
Section titled “MarkdownRenderOptions.fileURL”类型: URL
指定正在渲染的 Markdown 文件的 URL。
MarkdownRenderOptions.frontmatter
Section titled “MarkdownRenderOptions.frontmatter”类型: Record<string, any>
提供 Markdown 内容的 frontmatter 数据。
MarkdownRenderResult
Section titled “MarkdownRenderResult”类型: { code: string; metadata: { headings: MarkdownHeading[]; localImagePaths: string[]; remoteImagePaths: string[]; frontmatter: Record<string, any>; }; }
@astrojs/[email protected]
描述渲染后的 Markdown 文件。
MarkdownRenderResult.code
Section titled “MarkdownRenderResult.code”类型: string
包含渲染后的 HTML 代码。
MarkdownRenderResult.metadata
Section titled “MarkdownRenderResult.metadata”类型: { headings: MarkdownHeading[]; localImagePaths: string[]; remoteImagePaths: string[]; frontmatter: Record<string, any>; }
描述与内容关联的元数据。
MarkdownRenderResult.metadata.headings
Section titled “MarkdownRenderResult.metadata.headings”类型: MarkdownHeading[]
提取出的标题列表。
MarkdownRenderResult.metadata.localImagePaths
Section titled “MarkdownRenderResult.metadata.localImagePaths”类型: string[]
渲染内容中引用的本地图片路径数组。
MarkdownRenderResult.metadata.remoteImagePaths
Section titled “MarkdownRenderResult.metadata.remoteImagePaths”类型: string[]
渲染内容中引用的远程图片路径数组。
MarkdownRenderResult.metadata.frontmatter
Section titled “MarkdownRenderResult.metadata.frontmatter”类型: Record<string, any>
传递给渲染器的 frontmatter。
MarkdownRenderer
Section titled “MarkdownRenderer”类型: { render: (content: string, opts?: MarkdownRenderOptions) => Promise<MarkdownRenderResult>; }
@astrojs/[email protected]
指定独立 Markdown 处理器所实现的接口。
MarkdownRenderer.render()
Section titled “MarkdownRenderer.render()”类型: (content: string, opts?: MarkdownRenderOptions) => Promise<MarkdownRenderResult>
为给定的 Markdown 内容生成渲染后的 HTML 和元数据。你可以通过第二个参数中的选项自定义渲染过程。
RehypePlugin
Section titled “RehypePlugin”类型: Plugin<PluginParameters, HastRoot>
@astrojs/[email protected]
定义 unified 生态系统中的 rehype 插件。
RehypePlugins
Section titled “RehypePlugins”类型: (string | [string, any] | RehypePlugin | [RehypePlugin, any])[]
@astrojs/[email protected]
用于自定义 Markdown 内容生成的 HTML 输出的 rehype 插件列表。每一项可以是已导入的插件,也可以是 Astro 应自动导入的包名。
RemarkPlugin
Section titled “RemarkPlugin”类型: Plugin<PluginParameters, MdastRoot>
@astrojs/[email protected]
定义 unified 生态系统中的 remark 插件。
RemarkPlugins
Section titled “RemarkPlugins”类型: (string | [string, any] | RemarkPlugin | [RemarkPlugin, any])[]
@astrojs/[email protected]
用于自定义 Markdown 处理过程的 remark 插件列表。每一项可以是已导入的插件,也可以是 Astro 应自动导入的包名。
RemarkRehype
Section titled “RemarkRehype”类型: Record<string, unknown>
@astrojs/[email protected]
指定传递给 remark-rehype 插件的选项。
ShikiConfig
Section titled “ShikiConfig”类型: object
@astrojs/[email protected]
描述配置 Shiki 语法高亮器时使用的选项。
ShikiConfig.langs
Section titled “ShikiConfig.langs”类型: LanguageRegistration[]
启用语法高亮的 Shiki 语言列表。
ShikiConfig.langAlias
Section titled “ShikiConfig.langAlias”类型: Record<string, string>
定义将别名映射到 Shiki 语言 ID 的自定义规则。
有关更多信息,请参阅 Shiki 语言别名。
ShikiConfig.theme
Section titled “ShikiConfig.theme”类型: ThemePresets | ThemeRegistration | ThemeRegistrationRaw
指定语法高亮的默认主题。你可以使用 Shiki 内置主题或自定义 Shiki 主题。
ShikiConfig.themes
Section titled “ShikiConfig.themes”类型: Record<string, ThemePresets | ThemeRegistration | ThemeRegistrationRaw>
将主题名称映射到对应 Shiki 主题配置的对象。
ShikiConfig.defaultColor
Section titled “ShikiConfig.defaultColor”类型: 'light' | 'dark' | string | false
指定定义了 [ShikiConfig.themes] 时要使用的默认主题。
ShikiConfig.wrap
Section titled “ShikiConfig.wrap”类型: boolean | null
是否通过换行避免水平滚动。
ShikiConfig.transformers
Section titled “ShikiConfig.transformers”类型: ShikiTransformer[]
自定义生成 HTML 的 Shiki 转换器列表。
transformers 应用于 <Code />。
Smartypants
Section titled “Smartypants”类型: object
@astrojs/[email protected]
SyntaxHighlightConfig
Section titled “SyntaxHighlightConfig”类型: { type: SyntaxHighlightConfigType; excludeLangs?: string[]; }
@astrojs/[email protected]
SyntaxHighlightConfigType
Section titled “SyntaxHighlightConfigType”类型: 'shiki' | 'prism'
@astrojs/[email protected]
Astro 中支持的语法高亮器的联合类型。
Reference