TinaCMS MDX 解析器如何处理 Markdown 与 HTML 混排内容markdown-html-issues 测试用例深度解析【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms本篇技术指南以 TinaCMS 仓库中packages/tinacms/mdx/src/next/tests/markdown-html-issues/测试夹具为切入点剖析 TinaCMS 富文本rich-text字段在 Markdown 解析模式下如何应对以div、pre、code等 HTML 标签与 Markdown 语法混排的非标准内容。读完本文你将理解 TinaCMS 的 MDX 解析管线parse → AST → stringify 的往返流程、html与html_inline两种节点的语义差异以及如何通过源码级测试用例验证解析行为的正确性。一、测试用例的定位一个专门针对 HTML 混排问题的回归测试在 packages/tinacms/mdx/src/next/tests/ 目录下聚集了 70 余个针对 Markdown / MDX 解析行为的测试夹具每个夹具目录都是一个独立的输入 期望 AST 期望输出三元组。其中markdown-html-issues/专门用来覆盖Markdown 文本中混入大量手写 HTML这一现实场景——例如从 WordPress、GraphQL 教程博客等第三方系统迁移来的内容往往充斥着div class...、precode、内联code等原始 HTML 标记。该目录包含四个文件文件作用in.md测试输入一段混合了 Markdown 语法与手写 HTML 的富文本内容field.ts字段定义声明type: rich-text且parser.type markdown的配置node.json期望的解析后 AST由parseMDX产出的 JSON 快照index.test.ts测试入口执行 parse 与 stringify 的往返断言二、输入内容解剖in.md 里到底难在哪先看 in.md 的结构。它是一段 GraphQL 教程的代码片段但并非标准的 Markdown 代码块而是由一层层 HTML 标签包裹起来的伪代码块div classbreak-out precode classlanguage-javascriptimport React, {useState} from react import gql from graphql-tag .../code code classlanguage-javascript stylebackground-color: #fffbd7const GET_PETS gql query getPets { ... };/code code classlanguage-javascriptexport default function Pets () { ... }/code ... /code/pre /div这段输入给解析器带来了三个典型难题块级 HTML 与 Markdown 段落交错div classbreak-out、/pre、/div单独成行与后续的普通 Markdown 段落交替出现解析器必须正确区分这是 HTML 块还是这是普通段落。高亮代码的内联标记某些code标签带stylebackground-color: #fffbd7属性用于高亮展示新增代码。解析器不能把这些内容当作普通文本丢失也不能错误地提升为块级节点。HTML 实体的转义输入中大量出现lt;Loader /gt;、lt;div className...gt;等实体转义与代码块内的 JSX 语法混合需要正确处理。三、解析调用链parseMDX 如何把混排文本变成 ASTmarkdown-html-issues测试的核心断言对象是parseMDX它来自 packages/tinacms/mdx/src/next/parse/index.tsexport const parseMDX ( value: string, field: RichTextField, imageCallback?: (s: string) string ) { const backup (v: string) v; const callback imageCallback || backup; const tree fromMarkdown(value, field); return postProcess(tree, field, callback); }; const postProcess ( tree: Root, field: RichTextField, imageCallback: (s: string) string ) { // Some of our processing results in adjacent nodes of the same type return postProcessor(compact(tree), field, imageCallback); };这条调用链清晰揭示了 TinaCMS MDX 模块的两段式设计该实现注释中说明src/next是较新的解析器实现公共 APIparseMDX在处理 Markdown 内容时委托到这里fromMarkdown实现在 parse/markdown.ts先把原始字符串解析成 mdast 语法树其中 HTML 相关节点会被标记为html或html_inline类型postProcessor实现在 parse/post-processing.ts对树做后处理例如合并相邻的同类型节点注释中明确提到 Some of our processing results in adjacent nodes of the same type并通过compact折叠冗余节点最终得到干净、可被 TinaCMS 表单消费的 AST。测试入口 index.test.ts 把这条链固定下来import { parseMDX } from ../../../parse; import { serializeMDX } from ../../../stringify; import { field } from ./field; import input from ./in.md?raw; it(matches input, () { const tree parseMDX(input, field, (v) v); expect(util.print(tree)).toMatchFile(util.nodePath(__dirname)); const string serializeMDX(tree, field, (v) v); expect(string).toMatchFile(util.mdPath(__dirname)); });字段配置 field.ts 非常简单却决定了整条解析路径走的是 Markdown 而非 MDX 分支export const field: RichTextField { name: body, type: rich-text, parser: { type: markdown }, };四、AST 结果解读html 与 html_inline 的分野node.json 是这次解析的标准答案它揭示了 TinaCMS 对混排 HTML 的归类策略1. 独立的块级 HTML 成为html节点。开头的div classbreak-out\nprecode classlanguage-javascript...一整段被完整保留为{ type: html, value: div class\break-out\\nprecode class\language-javascript\import React, {useState} from react\n..., children: [{ type: text, text: }] }注意value字段完整保留了原始 HTML 字符串与换行符意味着解析与序列化往返后这段标记不会丢失。2. 与文本混排的内联标签成为html_inline节点。例如高亮代码段被拆解为{ type: p, children: [ { type: html_inline, value: code class\language-javascript\ style\background-color: #fffbd7\ }, { type: text, text: const GET_PETS gql }, { type: text, text: query getPets { ... }, code: true }, { type: text, text: ; }, { type: html_inline, value: /code } ] }这组节点非常典型包围高亮代码的code开闭标签被提升为html_inline节点而中间的代码正文则被识别为带code: true标记的 text 节点。这样 TinaCMS 编辑器既可以渲染高亮背景又不会把代码正文误判为普通段落。3. 后续的 JSX/HTML 片段被降级为纯文本段落。if (loading) return Loader /;、div classNamepage pets-page等原本写在pre内的内容在 AST 中被解析为多个独立的p节点内部的 JSX 以转义后的纯文本形式lt;Loader /gt;或html_inline节点出现。这说明解析器对半生不熟的 HTML采取了宽容策略能结构化的结构化不能结构化的保底为文本保证内容不丢。五、往返一致性serializeMDX 的闭环保障markdown-html-issues测试的第二半是序列化验证serializeMDX(tree, field, (v) v)再把 AST 写回 Markdown并用toMatchFile与期望输出比对。其实现位于 packages/tinacms/mdx/src/next/stringify/由 index.ts 统一导出内部经 to-markdown.ts 与 pre-processing.ts 完成 AST 到 Markdown 的还原。这一断言的意义在于TinaCMS 的编辑流程是读文件 → 解析成树 → 编辑器修改 → 序列化写回文件的闭环。如果只验证解析不验证序列化可能出现能读不能写的故障——用户在可视化编辑器中做了一次微小改动整篇混排 HTML 文档就被重排得面目全非。markdown-html-issues通过同时锁定两个方向的结果把这种风险扼杀在测试阶段。六、同类问题矩阵HTML 处理是 TinaCMS 的重点测试域markdown-html-issues并非孤例。在 tests 目录中还有一组同主题的相邻夹具共同构成 HTML 兼容性的测试矩阵markdown-basic-autoformat-htmlHTML 标签触发的自动格式化行为wordpress-style、wordpress-style-2、wordpress-style-2-block-with-children、wordpress-style-2-with-children模拟 WordPress 导出的带figure、img、figcaption等标签的内容markdown-shortcodes-* 系列HTML 作为 shortcode 子节点的场景mdx-jsx-* 系列MDX 模式下的 JSX 表达式属性。从这些用例的命名规律可以推断TinaCMS 将从其他 CMS/博客系统迁移进来的历史内容视为一等公民markdown-html-issues正是这套兼容策略在手写 HTML 代码块这一具体形态上的回归防线。七、对使用者的实践启示结合本测试夹具与解析器实现可以总结出在 TinaCMS 中使用 Markdown 模式富文本字段的几点实践建议parser.type决定解析分支在 tina 配置 中将字段声明为type: rich-text并显式设置parser: { type: markdown }即可让内容按本文所述的 Markdown 路径解析缺省或使用 MDX 模式时行为不同。HTML 内容可以放心迁移从 WordPress 或教程站拷贝的div/pre/code混排内容会分别落入html、html_inline、text三类节点编辑后写回不会丢内容——这正是markdown-html-issues每次 CI 都在守护的能力。验证解析行为的最快方式参考本夹具的组织方式在自己的仓库中复制in.md field.ts node.json index.test.ts四件套利用parseMDX/serializeMDX从 packages/tinacms/mdx/src/next/index.ts 导出即可获得输入 → AST → 输出的完整可回放验证链路。【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
TinaCMS MDX 解析器如何处理 Markdown 与 HTML 混排内容：markdown-html-issues 测试用例深度解析
TinaCMS MDX 解析器如何处理 Markdown 与 HTML 混排内容markdown-html-issues 测试用例深度解析【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms本篇技术指南以 TinaCMS 仓库中packages/tinacms/mdx/src/next/tests/markdown-html-issues/测试夹具为切入点剖析 TinaCMS 富文本rich-text字段在 Markdown 解析模式下如何应对以div、pre、code等 HTML 标签与 Markdown 语法混排的非标准内容。读完本文你将理解 TinaCMS 的 MDX 解析管线parse → AST → stringify 的往返流程、html与html_inline两种节点的语义差异以及如何通过源码级测试用例验证解析行为的正确性。一、测试用例的定位一个专门针对 HTML 混排问题的回归测试在 packages/tinacms/mdx/src/next/tests/ 目录下聚集了 70 余个针对 Markdown / MDX 解析行为的测试夹具每个夹具目录都是一个独立的输入 期望 AST 期望输出三元组。其中markdown-html-issues/专门用来覆盖Markdown 文本中混入大量手写 HTML这一现实场景——例如从 WordPress、GraphQL 教程博客等第三方系统迁移来的内容往往充斥着div class...、precode、内联code等原始 HTML 标记。该目录包含四个文件文件作用in.md测试输入一段混合了 Markdown 语法与手写 HTML 的富文本内容field.ts字段定义声明type: rich-text且parser.type markdown的配置node.json期望的解析后 AST由parseMDX产出的 JSON 快照index.test.ts测试入口执行 parse 与 stringify 的往返断言二、输入内容解剖in.md 里到底难在哪先看 in.md 的结构。它是一段 GraphQL 教程的代码片段但并非标准的 Markdown 代码块而是由一层层 HTML 标签包裹起来的伪代码块div classbreak-out precode classlanguage-javascriptimport React, {useState} from react import gql from graphql-tag .../code code classlanguage-javascript stylebackground-color: #fffbd7const GET_PETS gql query getPets { ... };/code code classlanguage-javascriptexport default function Pets () { ... }/code ... /code/pre /div这段输入给解析器带来了三个典型难题块级 HTML 与 Markdown 段落交错div classbreak-out、/pre、/div单独成行与后续的普通 Markdown 段落交替出现解析器必须正确区分这是 HTML 块还是这是普通段落。高亮代码的内联标记某些code标签带stylebackground-color: #fffbd7属性用于高亮展示新增代码。解析器不能把这些内容当作普通文本丢失也不能错误地提升为块级节点。HTML 实体的转义输入中大量出现lt;Loader /gt;、lt;div className...gt;等实体转义与代码块内的 JSX 语法混合需要正确处理。三、解析调用链parseMDX 如何把混排文本变成 ASTmarkdown-html-issues测试的核心断言对象是parseMDX它来自 packages/tinacms/mdx/src/next/parse/index.tsexport const parseMDX ( value: string, field: RichTextField, imageCallback?: (s: string) string ) { const backup (v: string) v; const callback imageCallback || backup; const tree fromMarkdown(value, field); return postProcess(tree, field, callback); }; const postProcess ( tree: Root, field: RichTextField, imageCallback: (s: string) string ) { // Some of our processing results in adjacent nodes of the same type return postProcessor(compact(tree), field, imageCallback); };这条调用链清晰揭示了 TinaCMS MDX 模块的两段式设计该实现注释中说明src/next是较新的解析器实现公共 APIparseMDX在处理 Markdown 内容时委托到这里fromMarkdown实现在 parse/markdown.ts先把原始字符串解析成 mdast 语法树其中 HTML 相关节点会被标记为html或html_inline类型postProcessor实现在 parse/post-processing.ts对树做后处理例如合并相邻的同类型节点注释中明确提到 Some of our processing results in adjacent nodes of the same type并通过compact折叠冗余节点最终得到干净、可被 TinaCMS 表单消费的 AST。测试入口 index.test.ts 把这条链固定下来import { parseMDX } from ../../../parse; import { serializeMDX } from ../../../stringify; import { field } from ./field; import input from ./in.md?raw; it(matches input, () { const tree parseMDX(input, field, (v) v); expect(util.print(tree)).toMatchFile(util.nodePath(__dirname)); const string serializeMDX(tree, field, (v) v); expect(string).toMatchFile(util.mdPath(__dirname)); });字段配置 field.ts 非常简单却决定了整条解析路径走的是 Markdown 而非 MDX 分支export const field: RichTextField { name: body, type: rich-text, parser: { type: markdown }, };四、AST 结果解读html 与 html_inline 的分野node.json 是这次解析的标准答案它揭示了 TinaCMS 对混排 HTML 的归类策略1. 独立的块级 HTML 成为html节点。开头的div classbreak-out\nprecode classlanguage-javascript...一整段被完整保留为{ type: html, value: div class\break-out\\nprecode class\language-javascript\import React, {useState} from react\n..., children: [{ type: text, text: }] }注意value字段完整保留了原始 HTML 字符串与换行符意味着解析与序列化往返后这段标记不会丢失。2. 与文本混排的内联标签成为html_inline节点。例如高亮代码段被拆解为{ type: p, children: [ { type: html_inline, value: code class\language-javascript\ style\background-color: #fffbd7\ }, { type: text, text: const GET_PETS gql }, { type: text, text: query getPets { ... }, code: true }, { type: text, text: ; }, { type: html_inline, value: /code } ] }这组节点非常典型包围高亮代码的code开闭标签被提升为html_inline节点而中间的代码正文则被识别为带code: true标记的 text 节点。这样 TinaCMS 编辑器既可以渲染高亮背景又不会把代码正文误判为普通段落。3. 后续的 JSX/HTML 片段被降级为纯文本段落。if (loading) return Loader /;、div classNamepage pets-page等原本写在pre内的内容在 AST 中被解析为多个独立的p节点内部的 JSX 以转义后的纯文本形式lt;Loader /gt;或html_inline节点出现。这说明解析器对半生不熟的 HTML采取了宽容策略能结构化的结构化不能结构化的保底为文本保证内容不丢。五、往返一致性serializeMDX 的闭环保障markdown-html-issues测试的第二半是序列化验证serializeMDX(tree, field, (v) v)再把 AST 写回 Markdown并用toMatchFile与期望输出比对。其实现位于 packages/tinacms/mdx/src/next/stringify/由 index.ts 统一导出内部经 to-markdown.ts 与 pre-processing.ts 完成 AST 到 Markdown 的还原。这一断言的意义在于TinaCMS 的编辑流程是读文件 → 解析成树 → 编辑器修改 → 序列化写回文件的闭环。如果只验证解析不验证序列化可能出现能读不能写的故障——用户在可视化编辑器中做了一次微小改动整篇混排 HTML 文档就被重排得面目全非。markdown-html-issues通过同时锁定两个方向的结果把这种风险扼杀在测试阶段。六、同类问题矩阵HTML 处理是 TinaCMS 的重点测试域markdown-html-issues并非孤例。在 tests 目录中还有一组同主题的相邻夹具共同构成 HTML 兼容性的测试矩阵markdown-basic-autoformat-htmlHTML 标签触发的自动格式化行为wordpress-style、wordpress-style-2、wordpress-style-2-block-with-children、wordpress-style-2-with-children模拟 WordPress 导出的带figure、img、figcaption等标签的内容markdown-shortcodes-* 系列HTML 作为 shortcode 子节点的场景mdx-jsx-* 系列MDX 模式下的 JSX 表达式属性。从这些用例的命名规律可以推断TinaCMS 将从其他 CMS/博客系统迁移进来的历史内容视为一等公民markdown-html-issues正是这套兼容策略在手写 HTML 代码块这一具体形态上的回归防线。七、对使用者的实践启示结合本测试夹具与解析器实现可以总结出在 TinaCMS 中使用 Markdown 模式富文本字段的几点实践建议parser.type决定解析分支在 tina 配置 中将字段声明为type: rich-text并显式设置parser: { type: markdown }即可让内容按本文所述的 Markdown 路径解析缺省或使用 MDX 模式时行为不同。HTML 内容可以放心迁移从 WordPress 或教程站拷贝的div/pre/code混排内容会分别落入html、html_inline、text三类节点编辑后写回不会丢内容——这正是markdown-html-issues每次 CI 都在守护的能力。验证解析行为的最快方式参考本夹具的组织方式在自己的仓库中复制in.md field.ts node.json index.test.ts四件套利用parseMDX/serializeMDX从 packages/tinacms/mdx/src/next/index.ts 导出即可获得输入 → AST → 输出的完整可回放验证链路。【免费下载链接】tinacmsTinaCMS is the leading open-source headless CMS that supports Markdown and Visual Editing. Your content is stored in your own GitHub repo ❤️项目地址: https://gitcode.com/GitHub_Trending/ti/tinacms创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
