企业官网建设流程全解析

Astro Markdoc 集成演化全解：从 0.0.1 到 2.0.9 的关键能力、配置语义与升级路径

【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro

本文以 packages/integrations/markdoc/CHANGELOG.md 为主线，系统梳理@astrojs/markdoc从 2023 年实验性引入（0.0.1）到当前 2.x 稳定版的完整演化轨迹，重点解读markdoc.config.mjs配置体系、render与transform的优先级语义、Markdoc 图片处理管线、extends扩展机制等开发者最关心的行为变更。阅读全文后，你将掌握这套集成的当前用法、历史遗留坑位，以及从旧版本安全迁移到新版本的具体路径。

认识 @astrojs/markdoc：它解决什么问题

@astrojs/markdoc是 Astro 官方的 Markdoc 集成，让.mdoc文件可以在 Astro 的 Content Collections 中被解析、渲染，并直接使用 Astro 组件与 UI 框架组件作为 Markdoc 的 tag 与 node 渲染目标。该包诞生于 0.0.1 版本，最初是实验性集成，其安装命令至今仍然有效：

astro add markdoc

从仓库内的 package.json 可以看到该包当前的工程形态：

• 版本为2.0.9，peerDependencies要求astro: ^7.0.0；
• 运行环境要求node: >=22.12.0（这是 1.0.0 升级时提高的最低版本）；
• 提供多个子路径导出：@astrojs/markdoc/config（配置辅助函数）、@astrojs/markdoc/prism与@astrojs/markdoc/shiki（语法高亮扩展）、@astrojs/markdoc/runtime（渲染运行时）以及@astrojs/markdoc/components；
• 关键运行依赖包括@markdoc/markdoc（Markdoc 核心）、@astrojs/prism、esbuild、github-slugger（生成标题锚点 id）与htmlparser2（2.0.4 起升级到 v12 用于 HTML 解析）。

配套的可运行参考项目位于 examples/with-markdoc，其中 astro.config.mjs 只做一行注册integrations: [markdoc()]，所有 Markdoc 专属定制都收敛到独立的 markdoc.config.mjs。

配置体系的三次跃迁（0.1.0 → 0.4.0 → 1.0.0）

第一次跃迁：独立 markdoc.config.mjs 诞生

0.1.0 是最具里程碑意义的一版：配置从astro.config中被拆出，新增独立的markdoc.config.mjs文件，以 default export 导出配置对象，并可选使用defineMarkdocConfig()获得编辑器自动补全。该阶段的典型写法是直接在配置文件中import Aside from './src/components/Aside.astro'并赋给tags.aside.render。同时，<Content />组件上原有的components={{ Aside }}属性被废弃——组件解析统一收归配置文件。

第二次跃迁：component() 工厂函数取代直接导入

0.4.0 引入component()函数，不再直接导入.astro组件。这样做带来了两个关键收益：其一，可以指定组件路径字符串而非模块对象，从而支持从 npm 包中引用组件以及.ts源文件；其二，避免了运行时对.astro文件的直接依赖。

迁移方式在 changelog 中给出：

// markdoc.config.mjs import { defineMarkdocConfig, component } from '@astrojs/markdoc/config'; export default defineMarkdocConfig({ tags: { aside: { render: component('./src/components/Aside.astro'), }, }, });

这一 API 至今未变。查看当前 src/config.ts 中的实现，component(pathnameOrPkgName, namedExport?)会根据传入路径是否为相对路径或绝对路径来判断组件来源属于local还是package，同时保留可选的namedExport，这正是"可以从 npm 包与.ts文件使用组件"的实现基础。另外，config.ts 中export const nodes = { ...Markdoc.nodes, heading }说明该集成默认在 Markdoc 内置 nodes 之上追加了一个headingnode，配合github-slugger生成标题 id。

Render类型（见 config.ts）允许三种值：ComponentConfig（即component()返回值）、AstroInstance['default']（直接导入的组件，兼容旧写法）或string。这也是为何旧文档中的直接导入写法在迁移后依然能被宽容处理的原因。

第三次跃迁：对齐 Astro 6/7 大版本

进入 1.0.0 后，集成开始跟随 Astro 主版本线的底层能力更迭：

• 随 Astro 6 将最低 Node.js 版本提升至 22.12.0（开发期曾临时降低以适配 Stackblitz，最终以官方支持策略为准）；
• Astro 6 将构建工具升级到 Vite 7，本集成紧随其后；
• Markdown 标题 id 的生成规则在 v6 中发生变化，本集成同步更新自身的标题 id 逻辑；
• 内部图片处理从已移除的emitESMImage()迁移到emitImageMetadata()，并在 1.0.0 中改用 Astro 新的emitClientAssetAPI 处理内容集合中的图片产物。

2.0.0 则随 Astro 7 一起升级到 Vite v8，也是本次 2.x 主版本的核心变化。

render 与 transform：谁说了算

围绕"自定义组件"与"内置 transform"的关系，changelog 记录了一系列关键修复，理解这条线能帮你避免最常见的 Markdoc 定制陷阱。

• 1.0.0（PR #15335）：修复了展开内置 node 配置（例如...Markdoc.nodes.fence）并同时指定自定义render组件时，内置transform()会覆盖掉自定义组件的 bug。修复后的规则是：当二者同时存在时，render优先于transform。从源码侧看，集成在渲染阶段对配置做预处理时会剥离 Markdoc 内置 transform，从而让自定义组件真正接管。

• 2.0.5（PR #17191）：此前检测"transform 是否尊重自定义 render"的判断只认识点号（dot notation）访问写法，导致当 tag/node 名称需要方括号访问（bracket access）时（典型如side-note这类含连字符的标签名，访问形如nodes['side-note']），自定义transform会被误删。修复后，判断逻辑开始识别方括号写法、可选链与空白字符。

• 2.0.5（PR #17460）：进一步修复当 tag 或 node 同时指定自定义render组件与自定义transform函数时，用户手写的 transform 被丢弃的问题。新的规则非常明确：用户自定义的 transform 永远保留，被移除的只是 Markdoc 内置 transform，从而保证自定义组件能够生效。

• 1.0.0 的另一处细节：Markdoc 内置的{% table %}tag 与同名tablenode 之间，如果只在其中一侧声明自定义属性，另一侧会因缺少声明而触发 "Invalid attribute" 校验错误。修复方式是自动在共享名称的 tags 与 nodes 之间同步自定义属性声明，用户在哪一侧声明都行。

综合来看，1.x/2.x 之后的推荐定制模式是：通过component()指定render，需要数据预处理时再放心编写自定义transform——两者可以共存且语义确定。

图片能力的演进：从相对路径到自动优化

Markdoc 内容中的图片是 changelog 贯穿始终的主题之一：

• 0.0.5：在experimental.assets时代首次支持 Markdoc 图片的自动优化。此后.mdoc文件里可以直接写相对路径或别名路径，交由 Astro 的资产管线处理：

  The Milky Way Galaxy Houston

• 0.9.0：支持自定义图片 tag。定义一个名为image的 tag 后，其src属性如果是本地图片会自动解析，并把解析结果以ImageMetadata类型传给底层组件作为srcprop；远程 URL 或绝对路径则仍以字符串传递：

  // markdoc.config.mjs import { component, defineMarkdocConfig, nodes } from '@astrojs/markdoc/config'; export default defineMarkdocConfig({ tags: { image: { attributes: nodes.image.attributes, render: component('./src/components/MarkdocImage.astro'), }, }, });

  --- // src/components/MarkdocImage.astro import { Image } from 'astro:assets'; interface Props { src: ImageMetadata | string; alt: string; width: number; height: number; } const { src, alt, width, height } = Astro.props; --- <Image {src} {alt} {width} {height} />

  在文档中则以{% image src="./astro-logo.png" alt="Astro Logo" width="100" height="100" %}方式调用。

• 0.9.1：修复了 MDX 与 Markdoc 中原图在"该保留/该删除"场景下判断错误的问题。

• 1.0.0：随着 Astro 6 的资产管线升级，内部改走emitImageMetadata()与emitClientAsset，保证既有图片行为不回归。若你从旧版本升级遇到图片产物异常，优先确认 Astro 版本配套是否满足 1.0.0 之后的 peer 依赖要求。

extends 扩展机制与语法高亮

0.3.0 引入extends数组配置，作为可复用的配置切片机制，并顺势提供了两个官方内建扩展：Shiki 与 Prism。典型用法：

// 使用 Shiki import { defineMarkdocConfig } from '@astrojs/markdoc/config'; import shiki from '@astrojs/markdoc/shiki'; export default defineMarkdocConfig({ extends: [shiki({ /* Shiki config options */ })], });

// 使用 Prism import { defineMarkdocConfig } from '@astrojs/markdoc/config'; import prism from '@astrojs/markdoc/prism'; export default defineMarkdocConfig({ extends: [prism()], });

这两个扩展的源码位于 src/extensions/shiki.ts 与 src/extensions/prism.ts，并在 package.json 中通过./shiki、./prism子路径独立导出。代码块的底层着色实现也经历过两次更换：0.5.0 移除旧版 shiki 主题名（material-darker需改名material-theme-darker，material-default改名material-theme等），0.6.0 将内部shiki替换为 ESM 友好的shikiji，高亮 HTML 标记随之略有精简（回退色从span移到code/pre上）——对视觉无影响，但依赖特定 HTML 结构做样式定制的用户需自查。此外 2.0.1 修复了"列表项内渲染 Shiki 高亮代码块导致崩溃"的问题，可见代码高亮与 Markdoc 嵌套结构兼容性也经过了专门打磨。

面向内容作者的语法与渲染细节

changelog 中还有一批直接影响.mdoc写作体验的行为：

• partial（0.9.5）：Markdoc partial 支持自动解析。可以在一个 entry 里引用其他.mdoc文件，file属性指向相对路径：

  {% partial file="my-partials/_diagram.mdoc" /%}

  被引用的my-partials/_diagram.mdoc会渲染到调用处。

• 变量与 frontmatter 的两次调整：0.0.4 引入$entry变量（可用{% $entry.data.title %}读取 frontmatter）；0.3.0 则移除自动生成的$entry，改为通过 prop 显式传入 frontmatter——<Content frontmatter={entry.data} />。若仍在使用$entry的旧内容，需按此方式改造。

• HTML 处理与注释：0.3.1 起允许.mdoc中书写 HTML 注释<!-- like this -->；若需要处理 Markdoc 文件内的全部 HTML（包括 tag/node 内部的 HTML 元素），可在 astro 配置中开启allowHTML（0.4.4 引入）。

• 标题 id：0.2.1 修复了相同标题在文档间 id 不一致的问题；0.2.0 起为所有 Markdoc 文件生成标题 id 并填充headings属性；0.13.0 增加 Astro 实验性配置experimental.headingIdCompat，默认 Astro 会为以特殊字符结尾的标题移除末尾-，开启该 flag 后生成的 id 与 GitHub、npm 等平台保持一致；1.0.0 起标题 id 生成规则跟随 Astro v6 新逻辑。

• 易用性选项：在 src/options.ts 中可以看到当前集成支持的三个配置项——allowHTML、ignoreIndentation与typographer。其中ignoreIndentation（0.7.0 引入）用于忽略代码块缩进对 Markdoc 解析的影响、提升源码可读性；typographer（0.11.2 引入）对应 Markdown-it 的 typographer 选项。

• 健壮性修复汇总：标签名含连字符导致构建失败（0.4.2）、document.render设为null时渲染无包裹元素/组件样式脚本正常输出（0.1.1、0.3.2、0.12.6）、if标签内的代码块渲染（0.12.5）、HTML 布尔属性正确渲染（0.12.0）、extends中配置的组件可用（0.11.4）、dev server 在 markdoc 配置变更后自动重启（0.4.0）、校验错误提供完整消息与文件预览（0.1.3）等。

版本速查与升级路径建议

综合 changelog 与 package.json，可给出如下快速定位表：

如果你的项目配置来自 0.1.0 时代（直接在render上挂组件对象），优先对照 0.4.0 的迁移说明改为component()写法；若内容使用了$entry，需在 0.3.0 之后按 prop 传入 frontmatter；若从 1.0.0 之前的版本升级到 2.x，则应同时升级 Astro 至 7.x 并确认 Node ≥ 22.12.0。源码侧可以随时对照 src/config.ts、src/options.ts 与 examples/with-markdoc（其中的 intro.mdoc 演示了{% table %}、{% aside %}、{% if %}等内置 tag 的组合使用）来验证当前版本的实际行为。理解了上述"从何而来、为何变更"，你就能在升级时预判破坏点，并在自定义 tags/nodes、图片与高亮行为上与集成保持一致的预期。

【免费下载链接】astroThe web framework for content-driven websites. ⭐️ Star to support our work!项目地址: https://gitcode.com/GitHub_Trending/as/astro