MDX是一种 Markdown 变体，允许用户嵌入用 JavaScript 和 React 的 JSX 模板语法编写的内容。与 Markdoc 一样，MDX 可以将 React 组件合并到一份文档中。关键区别在于 MDX 支持任意复杂的 JavaScript 逻辑（认为：文档作为代码），而 Markdoc 强制执行代码和内容之间的严格分离（认为：文档作为数据）。
Markdoc 使用完全声明的方法来组合和流控制，其中 MDX 依赖于 JavaScript 和 React。这意味着 MDX 为用户提供了更多的功能和灵活性，但以复杂性为代价——内容可能很快变得像常规代码一样复杂，这可能导致可维护性复杂化或更困难的创作环境。
在 Stripe 创建 Markdoc 的主要动机之一是创建一种格式，该格式针对编写而不是编程进行了优化，这样我们就可以克服在遗留文档平台中混合代码和内容所带来的挑战。借助 Markdoc，贡献者可以快速迭代，而无需对他们的编辑进行代码审查和我们必须应用于支持嵌入式 JavaScript 的格式的技术审查标准。Markdoc 还帮助加强对页面逻辑的控制，避免一次性黑客攻击和程序内容生成引入错误和不可预测行为的情况。
Markdoc 一流的声明性标记语法与 Markdown 内容无缝集成，可以更轻松地以统一、轻量级的方式处理内容转换、静态分析和验证。在 MDX 中，其中一些任务需要对更复杂的 JavaScript AST 进行操作，并考虑到所有 JavaScript 语言功能。MDX 还具有明显更大的运行时依赖足迹，并依赖于 JavaScript 解析器来处理嵌入式逻辑。
MDX 是一种书写格式，允许你在 Markdown 文档中无缝地插入 JSX 代码，还能导入（import）组件，例如交互式图表或弹框。写MDX应该熟悉 markdown 语法和 JavaScript 语法 (特别是 JSX)。Markdown 在标准化、结构化、组件化都存在硬伤，有了 MDX ，Markdown 有了富交互、内容形态的编写。
Markdoc是一种很有前途的新内容格式由Stripe开发。MDX 在处理大量文件时发现速度明显下降的情况并不少见。.mdoc格式比mdx有3倍速度的提升。Markdoc 的解析器是用 JavaScript 编写的，构建在一个名为markdown-it 的流行开源 Markdown 库之上。astro支持markdoc
Markdoc 是否符合 CommonMark 规范？
Markdoc 的语法在很大程度上是CommonMark 规范的超集。Markdoc 引入了它自己的句法扩展，包括标签、注释和变量插值。Markdoc 还支持GitHub 风格的表格，但我们鼓励您改用 Markdoc 自己的列表式表格。
Markdoc 不支持的唯一 CommonMark 指定功能是setext heading。这个设计决定在很大程度上是 Markdoc 核心团队的内部偏好：在我们看来，setext 标题与更常用的ATX 标题是多余的，并且引入了更多的歧义。如果你想在 Markdoc 中使用 setext 标题，或者你需要支持该功能以确保与现有内容的兼容性，你仍然可以重新配置 Markdoc 的分词器以重新启用 markdown-it规则
lheading。在符合 CommonMark 的 Markdown 中，任何缩进四个空格的内容都被视为代码块。不幸的是，这种行为使得难以使用任意级别的缩进来提高具有复杂结构的文档的可读性。
在 Markdoc 中使用嵌套标签时，缩进标签内的内容很有帮助，这样深度层次就清楚了。为了支持任意缩进，我们必须禁用基于缩进的代码块并修改其他几个考虑基于缩进的代码块的 markdown-it 解析规则。
我们起草了一份描述 Markdoc 标签语法的规范。我们欢迎第三方实施者采用和贡献 Markdoc 标签规范。标记语法是我们目前正式指定的 Markdoc 的唯一部分，但我们正在认真考虑为 Markdoc 的抽象语法树 (AST) 的 JSON 表示起草规范的可能性，以促进 Markdoc 工具之间的互操作性。
将来，我们可能会创建一种独特的 Markdown 方言，进一步偏离 CommonMark 规范，删除其他功能，例如可以由 Markdoc 标签替换的尖括号块引用语法。我们认为有机会专门为 Markdoc 创建一个 Markdown 变体，它不那么模糊、更具规范性，并且更有利于严格规范。这将与我们今天支持的 CommonMark 对齐语法一起提供，让用户可以选择是想要更简洁的语法还是与现有 Markdown 工具和内容的兼容性。
AsciiDoc是一种纯文本标记格式，专为技术写作而设计，融合了 DocBook 和其他出版技术的思想。AsciiDoc 获得了很多正确的东西——可扩展性、对高度结构化内容的支持、解析为 AST 和开放治理。
我们是 AsciiDoc 的忠实粉丝——当我们开始设计 Markdoc 时，它是主要的灵感来源。事实上，早在 2017 年，我们就对 Stripe 的内容格式进行了现代化改造，其中涉及基于 Ruby 的AsciiDoctor库构建的概念验证。随着我们努力的进展，我们最终转向 Markdown 而不是继续使用 AsciiDoc 有几个原因。
AsciiDoc 不如 Markdown 普遍存在，这意味着工程师和技术作家不太熟悉它。AsciiDoc 有许多句法特质，这会给采用者带来摩擦，使其很难卖给已经知道并想要 Markdown 的用户。例如，AsciiDoc 需要使用多个前导星号来表示嵌套的项目符号列表，因为该格式被设计为不将空格视为重要的。为了嵌套分隔的内容块，它依赖于改变分隔线的长度——不直观且容易出错的语法。
AsciiDoc 的可扩展性模型允许我们重新利用一些格式的内置模式来做我们在 Markdoc 中做的许多相同的事情，但以可用性为代价，因为 AsciiDoc 最终不是根据我们的需求和用例设计的头脑。Markdown 与 Markdoc 的语法扩展相结合，导致总体表面积小于 AsciiDoc 的功能集，这意味着复杂性更低，更容易采用。