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 為主線系統(tǒng)梳理astrojs/markdoc從 2023 年實驗性引入0.0.1到當前 2.x 穩(wěn)定版的完整演化軌跡重點解讀markdoc.config.mjs配置體系、render與transform的優(yōu)先級語義、Markdoc 圖片處理管線、extends擴展機制等開發(fā)者最關心的行為變更。閱讀全文后你將掌握這套集成的當前用法、歷史遺留坑位以及從舊版本安全遷移到新版本的具體路徑。認識 astrojs/markdoc它解決什么問題astrojs/markdoc是 Astro 官方的 Markdoc 集成讓.mdoc文件可以在 Astro 的 Content Collections 中被解析、渲染并直接使用 Astro 組件與 UI 框架組件作為 Markdoc 的 tag 與 node 渲染目標。該包誕生于 0.0.1 版本最初是實驗性集成其安裝命令至今仍然有效astro add markdoc從倉庫內的 package.json 可以看到該包當前的工程形態(tài)版本為2.0.9peerDependencies要求astro: ^7.0.0運行環(huán)境要求node: 22.12.0這是 1.0.0 升級時提高的最低版本提供多個子路徑導出astrojs/markdoc/config配置輔助函數、astrojs/markdoc/prism與astrojs/markdoc/shiki語法高亮擴展、astrojs/markdoc/runtime渲染運行時以及astrojs/markdoc/components關鍵運行依賴包括markdoc/markdocMarkdoc 核心、astrojs/prism、esbuild、github-slugger生成標題錨點 id與htmlparser22.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 }}屬性被廢棄——組件解析統(tǒng)一收歸配置文件。第二次躍遷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開發(fā)期曾臨時降低以適配 Stackblitz最終以官方支持策略為準Astro 6 將構建工具升級到 Vite 7本集成緊隨其后Markdown 標題 id 的生成規(guī)則在 v6 中發(fā)生變化本集成同步更新自身的標題 id 邏輯內部圖片處理從已移除的emitESMImage()遷移到emitImageMetadata()并在 1.0.0 中改用 Astro 新的emitClientAssetAPI 處理內容集合中的圖片產物。2.0.0 則隨 Astro 7 一起升級到 Vite v8也是本次 2.x 主版本的核心變化。render 與 transform誰說了算圍繞自定義組件與內置 transform的關系changelog 記錄了一系列關鍵修復理解這條線能幫你避免最常見的 Markdoc 定制陷阱。1.0.0PR #15335修復了展開內置 node 配置例如...Markdoc.nodes.fence并同時指定自定義render組件時內置transform()會覆蓋掉自定義組件的 bug。修復后的規(guī)則是當二者同時存在時render優(yōu)先于transform。從源碼側看集成在渲染階段對配置做預處理時會剝離 Markdoc 內置 transform從而讓自定義組件真正接管。2.0.5PR #17191此前檢測transform 是否尊重自定義 render的判斷只認識點號dot notation訪問寫法導致當 tag/node 名稱需要方括號訪問bracket access時典型如side-note這類含連字符的標簽名訪問形如nodes[side-note]自定義transform會被誤刪。修復后判斷邏輯開始識別方括號寫法、可選鏈與空白字符。2.0.5PR #17460進一步修復當 tag 或 node 同時指定自定義render組件與自定義transform函數時用戶手寫的 transform 被丟棄的問題。新的規(guī)則非常明確用戶自定義的 transform 永遠保留被移除的只是 Markdoc 內置 transform從而保證自定義組件能夠生效。1.0.0 的另一處細節(jié)Markdoc 內置的{% table %}tag 與同名tablenode 之間如果只在其中一側聲明自定義屬性另一側會因缺少聲明而觸發(fā) Invalid attribute 校驗錯誤。修復方式是自動在共享名稱的 tags 與 nodes 之間同步自定義屬性聲明用戶在哪一側聲明都行。綜合來看1.x/2.x 之后的推薦定制模式是通過component()指定render需要數據預處理時再放心編寫自定義transform——兩者可以共存且語義確定。圖片能力的演進從相對路徑到自動優(yōu)化Markdoc 內容中的圖片是 changelog 貫穿始終的主題之一0.0.5在experimental.assets時代首次支持 Markdoc 圖片的自動優(yōu)化。此后.mdoc文件里可以直接寫相對路徑或別名路徑交由 Astro 的資產管線處理The Milky Way Galaxy Houston0.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 altAstro Logo width100 height100 %}方式調用。0.9.1修復了 MDX 與 Markdoc 中原圖在該保留/該刪除場景下判斷錯誤的問題。1.0.0隨著 Astro 6 的資產管線升級內部改走emitImageMetadata()與emitClientAsset保證既有圖片行為不回歸。若你從舊版本升級遇到圖片產物異常優(yōu)先確認 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-darkermaterial-default改名material-theme等0.6.0 將內部shiki替換為 ESM 友好的shikiji高亮 HTML 標記隨之略有精簡回退色從span移到code/pre上——對視覺無影響但依賴特定 HTML 結構做樣式定制的用戶需自查。此外 2.0.1 修復了列表項內渲染 Shiki 高亮代碼塊導致崩潰的問題可見代碼高亮與 Markdoc 嵌套結構兼容性也經過了專門打磨。面向內容作者的語法與渲染細節(jié)changelog 中還有一批直接影響.mdoc寫作體驗的行為partial0.9.5Markdoc partial 支持自動解析?？梢栽谝粋€ entry 里引用其他.mdoc文件file屬性指向相對路徑{% partial filemy-partials/_diagram.mdoc /%}被引用的my-partials/_diagram.mdoc會渲染到調用處。變量與 frontmatter 的兩次調整0.0.4 引入$entry變量可用{% $entry.data.title %}讀取 frontmatter0.3.0 則移除自動生成的$entry改為通過 prop 顯式傳入 frontmatter——Content frontmatter{entry.data} /。若仍在使用$entry的舊內容需按此方式改造。HTML 處理與注釋0.3.1 起允許.mdoc中書寫 HTML 注釋!-- like this --若需要處理 Markdoc 文件內的全部 HTML包括 tag/node 內部的 HTML 元素可在 astro 配置中開啟allowHTML0.4.4 引入。標題 id0.2.1 修復了相同標題在文檔間 id 不一致的問題0.2.0 起為所有 Markdoc 文件生成標題 id 并填充headings屬性0.13.0 增加 Astro 實驗性配置experimental.headingIdCompat默認 Astro 會為以特殊字符結尾的標題移除末尾-開啟該 flag 后生成的 id 與 GitHub、npm 等平臺保持一致1.0.0 起標題 id 生成規(guī)則跟隨 Astro v6 新邏輯。易用性選項在 src/options.ts 中可以看到當前集成支持的三個配置項——allowHTML、ignoreIndentation與typographer。其中ignoreIndentation0.7.0 引入用于忽略代碼塊縮進對 Markdoc 解析的影響、提升源碼可讀性typographer0.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可給出如下快速定位表版本Astro 配套關鍵主題0.0.xAstro 2.x實驗性引入astro add markdoc$entry變量0.1.0Astro 2.1markdoc.config.mjs獨立配置文件、defineMarkdocConfig()0.3.0Astro 2.5移除$entryextends Shiki/Prism 擴展0.4.0Astro 2.7component()工廠函數取代直接導入0.9.0–0.9.5Astro 4.x/5.x自定義 image tag、partial 自動解析1.0.0Astro 6.xNode ≥ 22.12.0、Vite 7、emitImageMetadata/emitClientAsset、render 優(yōu)先于 transform、table tags/nodes 屬性同步2.0.0Astro 7.xVite 8htmlparser2 v12transform 保留語義細化2.0.5如果你的項目配置來自 0.1.0 時代直接在render上掛組件對象優(yōu)先對照 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、圖片與高亮行為上與集成保持一致的預期?！久赓M下載鏈接】astroThe web framework for content-driven websites. ?? Star to support our work!項目地址: https://gitcode.com/GitHub_Trending/as/astro創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 Astro Markdoc 集成演化全解：從 0.0.1 到 2.0.9 的關鍵能力、配置語義與升級路徑
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 為主線系統(tǒng)梳理astrojs/markdoc從 2023 年實驗性引入0.0.1到當前 2.x 穩(wěn)定版的完整演化軌跡重點解讀markdoc.config.mjs配置體系、render與transform的優(yōu)先級語義、Markdoc 圖片處理管線、extends擴展機制等開發(fā)者最關心的行為變更。閱讀全文后你將掌握這套集成的當前用法、歷史遺留坑位以及從舊版本安全遷移到新版本的具體路徑。認識 astrojs/markdoc它解決什么問題astrojs/markdoc是 Astro 官方的 Markdoc 集成讓.mdoc文件可以在 Astro 的 Content Collections 中被解析、渲染并直接使用 Astro 組件與 UI 框架組件作為 Markdoc 的 tag 與 node 渲染目標。該包誕生于 0.0.1 版本最初是實驗性集成其安裝命令至今仍然有效astro add markdoc從倉庫內的 package.json 可以看到該包當前的工程形態(tài)版本為2.0.9peerDependencies要求astro: ^7.0.0運行環(huán)境要求node: 22.12.0這是 1.0.0 升級時提高的最低版本提供多個子路徑導出astrojs/markdoc/config配置輔助函數、astrojs/markdoc/prism與astrojs/markdoc/shiki語法高亮擴展、astrojs/markdoc/runtime渲染運行時以及astrojs/markdoc/components關鍵運行依賴包括markdoc/markdocMarkdoc 核心、astrojs/prism、esbuild、github-slugger生成標題錨點 id與htmlparser22.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 }}屬性被廢棄——組件解析統(tǒng)一收歸配置文件。第二次躍遷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開發(fā)期曾臨時降低以適配 Stackblitz最終以官方支持策略為準Astro 6 將構建工具升級到 Vite 7本集成緊隨其后Markdown 標題 id 的生成規(guī)則在 v6 中發(fā)生變化本集成同步更新自身的標題 id 邏輯內部圖片處理從已移除的emitESMImage()遷移到emitImageMetadata()并在 1.0.0 中改用 Astro 新的emitClientAssetAPI 處理內容集合中的圖片產物。2.0.0 則隨 Astro 7 一起升級到 Vite v8也是本次 2.x 主版本的核心變化。render 與 transform誰說了算圍繞自定義組件與內置 transform的關系changelog 記錄了一系列關鍵修復理解這條線能幫你避免最常見的 Markdoc 定制陷阱。1.0.0PR #15335修復了展開內置 node 配置例如...Markdoc.nodes.fence并同時指定自定義render組件時內置transform()會覆蓋掉自定義組件的 bug。修復后的規(guī)則是當二者同時存在時render優(yōu)先于transform。從源碼側看集成在渲染階段對配置做預處理時會剝離 Markdoc 內置 transform從而讓自定義組件真正接管。2.0.5PR #17191此前檢測transform 是否尊重自定義 render的判斷只認識點號dot notation訪問寫法導致當 tag/node 名稱需要方括號訪問bracket access時典型如side-note這類含連字符的標簽名訪問形如nodes[side-note]自定義transform會被誤刪。修復后判斷邏輯開始識別方括號寫法、可選鏈與空白字符。2.0.5PR #17460進一步修復當 tag 或 node 同時指定自定義render組件與自定義transform函數時用戶手寫的 transform 被丟棄的問題。新的規(guī)則非常明確用戶自定義的 transform 永遠保留被移除的只是 Markdoc 內置 transform從而保證自定義組件能夠生效。1.0.0 的另一處細節(jié)Markdoc 內置的{% table %}tag 與同名tablenode 之間如果只在其中一側聲明自定義屬性另一側會因缺少聲明而觸發(fā) Invalid attribute 校驗錯誤。修復方式是自動在共享名稱的 tags 與 nodes 之間同步自定義屬性聲明用戶在哪一側聲明都行。綜合來看1.x/2.x 之后的推薦定制模式是通過component()指定render需要數據預處理時再放心編寫自定義transform——兩者可以共存且語義確定。圖片能力的演進從相對路徑到自動優(yōu)化Markdoc 內容中的圖片是 changelog 貫穿始終的主題之一0.0.5在experimental.assets時代首次支持 Markdoc 圖片的自動優(yōu)化。此后.mdoc文件里可以直接寫相對路徑或別名路徑交由 Astro 的資產管線處理The Milky Way Galaxy Houston0.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 altAstro Logo width100 height100 %}方式調用。0.9.1修復了 MDX 與 Markdoc 中原圖在該保留/該刪除場景下判斷錯誤的問題。1.0.0隨著 Astro 6 的資產管線升級內部改走emitImageMetadata()與emitClientAsset保證既有圖片行為不回歸。若你從舊版本升級遇到圖片產物異常優(yōu)先確認 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-darkermaterial-default改名material-theme等0.6.0 將內部shiki替換為 ESM 友好的shikiji高亮 HTML 標記隨之略有精簡回退色從span移到code/pre上——對視覺無影響但依賴特定 HTML 結構做樣式定制的用戶需自查。此外 2.0.1 修復了列表項內渲染 Shiki 高亮代碼塊導致崩潰的問題可見代碼高亮與 Markdoc 嵌套結構兼容性也經過了專門打磨。面向內容作者的語法與渲染細節(jié)changelog 中還有一批直接影響.mdoc寫作體驗的行為partial0.9.5Markdoc partial 支持自動解析?？梢栽谝粋€ entry 里引用其他.mdoc文件file屬性指向相對路徑{% partial filemy-partials/_diagram.mdoc /%}被引用的my-partials/_diagram.mdoc會渲染到調用處。變量與 frontmatter 的兩次調整0.0.4 引入$entry變量可用{% $entry.data.title %}讀取 frontmatter0.3.0 則移除自動生成的$entry改為通過 prop 顯式傳入 frontmatter——Content frontmatter{entry.data} /。若仍在使用$entry的舊內容需按此方式改造。HTML 處理與注釋0.3.1 起允許.mdoc中書寫 HTML 注釋!-- like this --若需要處理 Markdoc 文件內的全部 HTML包括 tag/node 內部的 HTML 元素可在 astro 配置中開啟allowHTML0.4.4 引入。標題 id0.2.1 修復了相同標題在文檔間 id 不一致的問題0.2.0 起為所有 Markdoc 文件生成標題 id 并填充headings屬性0.13.0 增加 Astro 實驗性配置experimental.headingIdCompat默認 Astro 會為以特殊字符結尾的標題移除末尾-開啟該 flag 后生成的 id 與 GitHub、npm 等平臺保持一致1.0.0 起標題 id 生成規(guī)則跟隨 Astro v6 新邏輯。易用性選項在 src/options.ts 中可以看到當前集成支持的三個配置項——allowHTML、ignoreIndentation與typographer。其中ignoreIndentation0.7.0 引入用于忽略代碼塊縮進對 Markdoc 解析的影響、提升源碼可讀性typographer0.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可給出如下快速定位表版本Astro 配套關鍵主題0.0.xAstro 2.x實驗性引入astro add markdoc$entry變量0.1.0Astro 2.1markdoc.config.mjs獨立配置文件、defineMarkdocConfig()0.3.0Astro 2.5移除$entryextends Shiki/Prism 擴展0.4.0Astro 2.7component()工廠函數取代直接導入0.9.0–0.9.5Astro 4.x/5.x自定義 image tag、partial 自動解析1.0.0Astro 6.xNode ≥ 22.12.0、Vite 7、emitImageMetadata/emitClientAsset、render 優(yōu)先于 transform、table tags/nodes 屬性同步2.0.0Astro 7.xVite 8htmlparser2 v12transform 保留語義細化2.0.5如果你的項目配置來自 0.1.0 時代直接在render上掛組件對象優(yōu)先對照 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、圖片與高亮行為上與集成保持一致的預期?！久赓M下載鏈接】astroThe web framework for content-driven websites. ?? Star to support our work!項目地址: https://gitcode.com/GitHub_Trending/as/astro創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考