Angular 文档管线中的自定义 Markdown 图片语法docs-image 扩展从分词到渲染的完整解析【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular本文基于 Angular 仓库文档站点angular.dev构建管线中的图片语法测试文档adev/shared-docs/pipeline/shared/marked/test/image/image.md系统讲解 Angular 文档管线如何用 marked 自定义扩展docs-image让文档作者在 Markdown 图片语法中直接声明loading、decoding、fetchpriority等 HTML 性能属性。读完后你将掌握该图片语法的完整写法、底层 Tokenizer 与 Renderer 的实现细节以及 Bazel JSDOM 测试如何逐项验证渲染结果。image.md 在文档管线中的定位image.md并不是一篇面向终端用户的指南而是 Angular 官方文档站点前端adev/即 angular.dev 的源码工程Markdown 渲染管线中docs-image 图片扩展的测试夹具fixture。它与同目录的规格文件 image.spec.mts 配对规格文件通过 JSDOM 把image.md解析为 HTML 片段再对其中每一张img断言具体的 class 与属性。该管线的工作入口在 parse.mts其中extensions数组注册了全部 18 个自定义扩展docsImageExtension位列其中见 parse.mts#L30-L49renderer.mts 中的AdevDocsRenderer则通过override image imageRender把图片渲染接管到自定义转换函数见 renderer.mts#L94。语法全貌image.md 中的六个用例image.md全文如下每一行演示图片扩展的一个能力点 New Logo!    逐行拆解其覆盖的能力行演示能力关键写法1外部图片 title(url Our new icon)单引号标题2站内相对路径图片./some-image.png触发 base path 前缀拼接3加载策略属性{loading: lazy}4解码策略属性 title 并存{decoding: async} Async Image属性块在前、title 在后5抓取优先级属性{fetchpriority: high}6多属性组合 title{loading: eager, decoding: sync, fetchpriority: high} Hero Image可以把它理解为“标准 Markdown 图片语法alt的超集”在 URL 与 title 之间额外支持一个以{key: value, ...}形式书写的属性块其中被识别的键是loading、decoding、fetchpriority三个 HTMLimg性能属性取值语义遵循浏览器 HTML 规范本扩展本身只做透传、不做取值校验这一点从源码结构看是成立的——Tokenizer 仅按正则提取字符串。Tokenizer 实现docs-image 扩展如何解析图片行扩展定义在 docs-image.mts它向 marked 注册了一个名为docs-image的inline 级自定义扩展。核心是这条主正则docs-image.mts#L17-L18// 匹配图片语法alt 或 alt const imageRule /^!\[([^\]]*)\]\(([^)\s])(?:\s\{([^}])\})?(?:\s[])?\)/;四个捕获组的含义([^\]]*)—— alt 文本text允许为空([^)\s])—— 图片地址href不允许包含空格和右括号因此属性块必须与 URL 之间有空格分隔(\{([^}])\})—— 可选的属性块{...}整块内容暂存为metadataStr([])—— 可选的单引号或双引号 title。随后Tokenizer 用三条子正则从属性块中分别提取三个性能属性docs-image.mts#L34-L36const loadingRule /loading\s*:\s*([])([^])\1/; const decodingRule /decoding\s*:\s*([])([^])\1/; const fetchpriorityRule /fetchpriority\s*:\s*([])([^])\1/;值得注意的细节是引号捕获组([\])配合反向引用\1属性值可以用单引号、双引号或反引号包裹如{loading: lazy}与{fetchpriority: high}均可解析这对在 Markdown 源码里嵌套引号的书写习惯很友好。解析结果被组装进扩展的DocsImagetoken[docs-image.mts#L11-L15](https://link.gitcode.com/i/db5ece72a5a16af762686ca861e5e0b3#L11-L15)即在标准Tokens.Image的href、title、text 基础上新增三个可选字段export interface DocsImage extends Tokens.Image { loading?: string; decoding?: string; fetchpriority?: string; }若图片行不符合该正则例如普通行内文本tokenizer返回undefined交给 marked 的默认解析流程继续尝试保证不会误吞非图片内容。渲染转换从 DocsImage token 到 标签拿到 token 后transformations/image.mts 中的imageRender负责生成最终 HTMLimage.mts#L17-L38// TODO(josephperrott): Determine how we can define/know the image content base path. const imageContentBasePath unknown; export function imageRender(this: Renderer, token: DocsImage) { const {href, title, text, loading, decoding, fetchpriority} token; const isRelativeSrc href?.startsWith(./); const src isRelativeSrc ? ${imageContentBasePath}/${normalize(href)} : href; const attrs [ src${src}, alt${text}, classdocs-image, title ? title${title} : null, loading ? loading${loading} : null, decoding ? decoding${decoding} : null, fetchpriority ? fetchpriority${fetchpriority} : null, ] .filter(Boolean) .join( ); return img ${attrs} ; }这里有三个值得注意的行为统一样式类所有文档图片一律输出classdocs-image便于站点层用一条 SCSS 选择器统一约束图片的圆角、阴影、最大宽度等外观而不是散落在各文档中。相对路径的 base path 拼接只有以./开头的href会被判定为站内图片并与imageContentBasePath拼接同时用path.normalize规整./、../等冗余片段外部http(s)地址原样输出。当前常量是字符串unknown源码中保留了 TODO 注释说明该内容基础路径仍待确定从源码结构看渲染阶段仅做字符串拼接并不会校验图片文件是否真实存在因此测试夹具中的./some-image.png即使没有对应实体文件也不影响解析。按需输出属性title、loading、decoding、fetchpriority四项采用“有值才拼接”的策略filter(Boolean)未声明的属性不会在 HTML 中留下空值属性保证输出标签干净。以image.md最后一行组合用例为例渲染产物为img srchttps://angular.dev/assets/logo.svg altCombined Attributes classdocs-image titleHero Image loadingeager decodingsync fetchpriorityhigh而第三行{loading: lazy}的用例则只多出loadinglazy一个属性。测试如何验证JSDOM 断言与 Bazel 目标image.spec.mts 用 JSDOM 的JSDOM.fragment将解析结果还原为 DOM 片段然后按querySelectorAll(img)的顺序逐张断言恰好一一对应image.md的六行img.classList.contains(docs-image)—— 验证统一样式类img[titleLocal Image]的src应等于unknown/some-image.png—— 验证相对路径被拼接了unknownbase path第 3 张图loading lazy第 4 张图decoding async且title Async Image验证属性块与 title 可并存第 5 张图fetchpriority high第 6 张图同时断言loading eager、decoding sync、fetchpriority high、title Hero Image见 image.spec.mts#L49-L55。测试所用的渲染上下文来自 renderer-context.mts它构造了一个RendererContext含示例apiEntries映射、空的headerIds等高亮器shiki因初始化是异步的而被置空。构建侧BUILD.bazel 定义了两个目标ts_projecttestonly编译**/*.spec.mts依赖 jsdom 与被测管线和zoneless_jasmine_test名为testdata中显式列出image.md与编译产物——这也解释了为什么image.md必须作为 Bazel 数据依赖声明否则测试运行时会找不到夹具。文档作者视角在 angular.dev 内容中怎么写图对维护adev/src/content/下 Markdown 内容的作者来说这套扩展意味着三种常见图片写法 !-- 普通图仅 alt title --  !-- 高优先级首屏图 -- 附录图 !-- 视口外/长文档中的懒加载图 --其中以./开头的路径会被当作站内资源并拼接内容 base path当前实现中该 base path 为unknown见 transformations/image.mts#L14-L15绝对 URL 则原样保留属性块内三个键的书写顺序不影响解析结果因为各键由独立的子正则提取属性值建议遵循 HTML 规范取值loading: eager | lazydecoding: auto | sync | asyncfetchpriority: auto | high | low扩展本身透传任意字符串取值合法性由浏览器侧保证——image.md夹具中实际使用的取值即lazy、eager、async、sync、high。小结与延伸阅读image.md作为一份仅 6 行的测试夹具精确锚定了 angular.dev 文档管线图片扩展的行为边界属性块语法、相对路径处理、属性透传与统一docs-image类。围绕它的实现链是语法解析extensions/docs-image.mtsinline 扩展 主正则 三属性子正则HTML 生成transformations/image.mtsimageRender、unknownbase path、按需输出属性注册与接管parse.mts扩展数组、renderer.mtsAdevDocsRenderer.override image行为验证test/image/image.spec.mts test/image/BUILD.bazelBazelzoneless_jasmine_testdata声明夹具同一test/目录下的code、link、table、heading等兄弟夹具采用完全相同的“md 夹具 spec 断言 Bazel 目标”组织方式是理解 Angular 文档管线其余标记能力的良好入口。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Angular 文档管线中的自定义 Markdown 图片语法：docs-image 扩展从分词到渲染的完整解析
Angular 文档管线中的自定义 Markdown 图片语法docs-image 扩展从分词到渲染的完整解析【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular本文基于 Angular 仓库文档站点angular.dev构建管线中的图片语法测试文档adev/shared-docs/pipeline/shared/marked/test/image/image.md系统讲解 Angular 文档管线如何用 marked 自定义扩展docs-image让文档作者在 Markdown 图片语法中直接声明loading、decoding、fetchpriority等 HTML 性能属性。读完后你将掌握该图片语法的完整写法、底层 Tokenizer 与 Renderer 的实现细节以及 Bazel JSDOM 测试如何逐项验证渲染结果。image.md 在文档管线中的定位image.md并不是一篇面向终端用户的指南而是 Angular 官方文档站点前端adev/即 angular.dev 的源码工程Markdown 渲染管线中docs-image 图片扩展的测试夹具fixture。它与同目录的规格文件 image.spec.mts 配对规格文件通过 JSDOM 把image.md解析为 HTML 片段再对其中每一张img断言具体的 class 与属性。该管线的工作入口在 parse.mts其中extensions数组注册了全部 18 个自定义扩展docsImageExtension位列其中见 parse.mts#L30-L49renderer.mts 中的AdevDocsRenderer则通过override image imageRender把图片渲染接管到自定义转换函数见 renderer.mts#L94。语法全貌image.md 中的六个用例image.md全文如下每一行演示图片扩展的一个能力点 New Logo!    逐行拆解其覆盖的能力行演示能力关键写法1外部图片 title(url Our new icon)单引号标题2站内相对路径图片./some-image.png触发 base path 前缀拼接3加载策略属性{loading: lazy}4解码策略属性 title 并存{decoding: async} Async Image属性块在前、title 在后5抓取优先级属性{fetchpriority: high}6多属性组合 title{loading: eager, decoding: sync, fetchpriority: high} Hero Image可以把它理解为“标准 Markdown 图片语法alt的超集”在 URL 与 title 之间额外支持一个以{key: value, ...}形式书写的属性块其中被识别的键是loading、decoding、fetchpriority三个 HTMLimg性能属性取值语义遵循浏览器 HTML 规范本扩展本身只做透传、不做取值校验这一点从源码结构看是成立的——Tokenizer 仅按正则提取字符串。Tokenizer 实现docs-image 扩展如何解析图片行扩展定义在 docs-image.mts它向 marked 注册了一个名为docs-image的inline 级自定义扩展。核心是这条主正则docs-image.mts#L17-L18// 匹配图片语法alt 或 alt const imageRule /^!\[([^\]]*)\]\(([^)\s])(?:\s\{([^}])\})?(?:\s[])?\)/;四个捕获组的含义([^\]]*)—— alt 文本text允许为空([^)\s])—— 图片地址href不允许包含空格和右括号因此属性块必须与 URL 之间有空格分隔(\{([^}])\})—— 可选的属性块{...}整块内容暂存为metadataStr([])—— 可选的单引号或双引号 title。随后Tokenizer 用三条子正则从属性块中分别提取三个性能属性docs-image.mts#L34-L36const loadingRule /loading\s*:\s*([])([^])\1/; const decodingRule /decoding\s*:\s*([])([^])\1/; const fetchpriorityRule /fetchpriority\s*:\s*([])([^])\1/;值得注意的细节是引号捕获组([\])配合反向引用\1属性值可以用单引号、双引号或反引号包裹如{loading: lazy}与{fetchpriority: high}均可解析这对在 Markdown 源码里嵌套引号的书写习惯很友好。解析结果被组装进扩展的DocsImagetoken[docs-image.mts#L11-L15](https://link.gitcode.com/i/db5ece72a5a16af762686ca861e5e0b3#L11-L15)即在标准Tokens.Image的href、title、text 基础上新增三个可选字段export interface DocsImage extends Tokens.Image { loading?: string; decoding?: string; fetchpriority?: string; }若图片行不符合该正则例如普通行内文本tokenizer返回undefined交给 marked 的默认解析流程继续尝试保证不会误吞非图片内容。渲染转换从 DocsImage token 到 标签拿到 token 后transformations/image.mts 中的imageRender负责生成最终 HTMLimage.mts#L17-L38// TODO(josephperrott): Determine how we can define/know the image content base path. const imageContentBasePath unknown; export function imageRender(this: Renderer, token: DocsImage) { const {href, title, text, loading, decoding, fetchpriority} token; const isRelativeSrc href?.startsWith(./); const src isRelativeSrc ? ${imageContentBasePath}/${normalize(href)} : href; const attrs [ src${src}, alt${text}, classdocs-image, title ? title${title} : null, loading ? loading${loading} : null, decoding ? decoding${decoding} : null, fetchpriority ? fetchpriority${fetchpriority} : null, ] .filter(Boolean) .join( ); return img ${attrs} ; }这里有三个值得注意的行为统一样式类所有文档图片一律输出classdocs-image便于站点层用一条 SCSS 选择器统一约束图片的圆角、阴影、最大宽度等外观而不是散落在各文档中。相对路径的 base path 拼接只有以./开头的href会被判定为站内图片并与imageContentBasePath拼接同时用path.normalize规整./、../等冗余片段外部http(s)地址原样输出。当前常量是字符串unknown源码中保留了 TODO 注释说明该内容基础路径仍待确定从源码结构看渲染阶段仅做字符串拼接并不会校验图片文件是否真实存在因此测试夹具中的./some-image.png即使没有对应实体文件也不影响解析。按需输出属性title、loading、decoding、fetchpriority四项采用“有值才拼接”的策略filter(Boolean)未声明的属性不会在 HTML 中留下空值属性保证输出标签干净。以image.md最后一行组合用例为例渲染产物为img srchttps://angular.dev/assets/logo.svg altCombined Attributes classdocs-image titleHero Image loadingeager decodingsync fetchpriorityhigh而第三行{loading: lazy}的用例则只多出loadinglazy一个属性。测试如何验证JSDOM 断言与 Bazel 目标image.spec.mts 用 JSDOM 的JSDOM.fragment将解析结果还原为 DOM 片段然后按querySelectorAll(img)的顺序逐张断言恰好一一对应image.md的六行img.classList.contains(docs-image)—— 验证统一样式类img[titleLocal Image]的src应等于unknown/some-image.png—— 验证相对路径被拼接了unknownbase path第 3 张图loading lazy第 4 张图decoding async且title Async Image验证属性块与 title 可并存第 5 张图fetchpriority high第 6 张图同时断言loading eager、decoding sync、fetchpriority high、title Hero Image见 image.spec.mts#L49-L55。测试所用的渲染上下文来自 renderer-context.mts它构造了一个RendererContext含示例apiEntries映射、空的headerIds等高亮器shiki因初始化是异步的而被置空。构建侧BUILD.bazel 定义了两个目标ts_projecttestonly编译**/*.spec.mts依赖 jsdom 与被测管线和zoneless_jasmine_test名为testdata中显式列出image.md与编译产物——这也解释了为什么image.md必须作为 Bazel 数据依赖声明否则测试运行时会找不到夹具。文档作者视角在 angular.dev 内容中怎么写图对维护adev/src/content/下 Markdown 内容的作者来说这套扩展意味着三种常见图片写法 !-- 普通图仅 alt title --  !-- 高优先级首屏图 -- 附录图 !-- 视口外/长文档中的懒加载图 --其中以./开头的路径会被当作站内资源并拼接内容 base path当前实现中该 base path 为unknown见 transformations/image.mts#L14-L15绝对 URL 则原样保留属性块内三个键的书写顺序不影响解析结果因为各键由独立的子正则提取属性值建议遵循 HTML 规范取值loading: eager | lazydecoding: auto | sync | asyncfetchpriority: auto | high | low扩展本身透传任意字符串取值合法性由浏览器侧保证——image.md夹具中实际使用的取值即lazy、eager、async、sync、high。小结与延伸阅读image.md作为一份仅 6 行的测试夹具精确锚定了 angular.dev 文档管线图片扩展的行为边界属性块语法、相对路径处理、属性透传与统一docs-image类。围绕它的实现链是语法解析extensions/docs-image.mtsinline 扩展 主正则 三属性子正则HTML 生成transformations/image.mtsimageRender、unknownbase path、按需输出属性注册与接管parse.mts扩展数组、renderer.mtsAdevDocsRenderer.override image行为验证test/image/image.spec.mts test/image/BUILD.bazelBazelzoneless_jasmine_testdata声明夹具同一test/目录下的code、link、table、heading等兄弟夹具采用完全相同的“md 夹具 spec 断言 Bazel 目标”组织方式是理解 Angular 文档管线其余标记能力的良好入口。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
