企业官网建设流程全解析

• 前端
• UI组件
• 异步编程

本文围绕 Textual 仓库中examples/example.md这一 Markdown 演示文档展开，系统梳理 Textual 内置Markdown与MarkdownViewer组件对标准 Markdown 语法的支持范围，包括标题、排版、列表、代码围栏、引用、表格等六大能力域，并结合src/textual/widgets/_markdown.py源码与examples/markdown.py应用示例，说明其底层实现原理与如何在自己应用中复现同样的展示效果。读者读完后，将能准确判断 Textual Markdown 组件的功能边界，并写出可完整渲染的 Markdown 文档。

定位：example.md 是 Markdown 组件的能力清单

examples/example.md并非一篇普通的说明文档，而是一份由 Textual 官方提供的Markdown 组件功能演示文件。它的用途很明确：当你在终端中运行 examples/markdown.py 时，MarkdownViewer组件会加载并渲染这个文件，从而直观展示组件支持的各种 Markdown 语法。

演示入口的关系链如下：

1. examples/markdown.py 中，path = var(Path(__file__).parent / "demo.md")定义了应用启动时默认加载demo.md；
2. demo.md末尾通过相对链接引导读者打开 example.md（原文为[example.md](https://link.gitcode.com/i/51cbd06f776469351dae9bddad7e25a1)，在本仓库中即examples/example.md）查看更丰富的语法示例；
3. example.md全文因此按"能渲染什么、就演示什么"的原则组织，覆盖了标题、排版、列表、代码、引用、表格等常用语法。

如何运行这份演示

在仓库根目录执行以下命令即可看到MarkdownViewer渲染example.md的真实效果（需要先在 pyproject.toml 所在环境安装 Textual 依赖）：

cd textual/examples python markdown.py example.md

从 examples/markdown.py 可以看到，应用支持在命令行传入一个存在的文件路径来替换默认文档：

if __name__ == "__main__": app = MarkdownApp() if len(argv) > 1 and Path(argv[1]).exists(): app.path = Path(argv[1]) app.run()

也就是说，python markdown.py 你的文件.md就能用同一套渲染管线浏览任意本地 Markdown 文件。

MarkdownViewer 的按键与导航能力

examples/markdown.py中还展示了MarkdownViewer的配套交互能力，这些在example.md的静态演示之外构成了完整的阅读体验：

对应源码见 examples/markdown.py。其中back/forward依赖MarkdownViewer.navigator这一导航栈实现——在 src/textual/widgets/_markdown.py 中，Navigator内部维护一个路径栈，go()压栈、back()/forward()移动栈指针；examples/markdown.py 还通过check_action在栈首/栈尾时禁用对应按键，避免无意义的导航。

标题：H1 至 H6 的完整支持

example.md首先验证的是标题层级："Headers levels 1 through 6 are supported."——即 Markdown 的六级标题全部支持。

从源码看，这一能力由MarkdownHeader基类及其六个子类MarkdownH1~MarkdownH6实现，见 src/textual/widgets/_markdown.py。每个子类都有独立的DEFAULT_CSS，例如：

• MarkdownH1：水平居中，使用$markdown-h1-color/$markdown-h1-background/$markdown-h1-text-style三个设计令牌；
• MarkdownH2：同样使用$markdown-h2-*系列令牌；
• MarkdownH3~MarkdownH6：各自绑定$markdown-h3-*至$markdown-h6-*令牌。

这意味着你可以在自己的 TCSS 中直接覆写MarkdownH1、MarkdownH2等选择器，或者通过调整$markdown-h1-color这类设计令牌，来定制各级标题的配色与字形，而不必改动渲染逻辑。

此外，example.md中出现的多级标题会被自动收集进目录侧边栏。这一点由MarkdownTableOfContents组件承载（src/textual/widgets/_markdown.py），标题的层级、标签与块 ID 以三元组形式记录（TableOfContentsType，见 src/textual/widgets/_markdown.py），TOC 点击时通过块 ID 定位并滚动到对应标题。

排版：强调、加粗、删除线与行内代码

example.md的 Typography 一节覆盖了四类行内排版语法，并明确提示"最终输出取决于你的终端，但大多数终端表现一致"：

• 强调（Emphasis）：*asterisks*渲染为like this；
• 加粗（Strong）：**strong**渲染为strong；
• 删除线（Strikethrough）：~~cross out~~渲染为cross out；
• 行内代码（Inline code）：反引号包裹，如`import this`。

源码层面的映射非常直接：MarkdownBlock.COMPONENT_CLASSES定义了em、strong、s、code_inline四个组件类（src/textual/widgets/_markdown.py），行内解析器在遍历 token 时（见 src/textual/widgets/_markdown.py）遇到em_open、strong_open、s_open、code_inline会分别压入对应样式 span，最终通过Content与Span组合渲染。注释还特别提醒：随意改动这些组件类可能导致标准 Markdown 格式失效。

在 TCSS 中，你可以通过以下方式微调行内样式：

MarkdownBlock code_inline { color: $text; background: $panel; }

分隔线：Horizontal Rule

example.md演示了用三个短横线---绘制水平分隔线，用于内容上的自然分节。

对应实现是MarkdownHorizontalRule（src/textual/widgets/_markdown.py），其默认样式在区块底部绘制一条solid $secondary边框，并设置了height: 1与上下内边距，保证视觉上与正文段落有明显区分。

列表：有序、无序与任意层级嵌套

example.md的 Lists 一节同时验证了有序列表、无序列表以及多层嵌套（缩进最多到第 5 层子项）。值得注意的一点是，文件中的嵌套列表同时混用了缩进结构，Textual 都能正确渲染。

源码中列表体系由以下类构成（src/textual/widgets/_markdown.py）：

• MarkdownList：列表基类，宽度1fr；
• MarkdownBulletList：无序列表，compose()中为每个MarkdownListItem生成一个圆点符号MarkdownBullet，并与项内容放入一个Horizontal容器；
• MarkdownOrderedList：有序列表，compose()会根据起始编号计算编号位数，从而对齐各编号后的文本缩进（symbol_size = max(len(f"{number}{suffix}") ...)）；
• 嵌套列表通过Vertical容器递归组合实现。

示例中还包含一个"较长列表"——example.md用 11 个带加粗姓名的条目验证了长列表场景下，编号对齐与加粗排版依然稳定。在终端字体为等宽字体的前提下，编号占位宽度会被统一计算，保证可读性。

代码围栏：语法高亮与缩进参考线

example.md的 Fences 一节展示了一个python语言标注的围栏代码块，并说明它"在子组件中以语法高亮和缩进参考线渲染"。原文档还展望了未来可能的"导出代码、复制到剪贴板、甚至运行并显示输出"等功能——这些属于作者的规划性描述，当前版本以静态高亮渲染为主。

实现上，代码围栏对应MarkdownFence组件，语法高亮依赖仓库中的 tree-sitter 语法定义，例如 Python 高亮规则位于 src/textual/tree-sitter/highlights/python.scm（example.md内嵌示例中使用的正是 Python 语法）。围栏块由 examples/example.md 中三反引号加语言标识引入，渲染时语言名会被用于选择对应的语法解析器。

引用：块引用与嵌套引用

example.md的 Quote 一节验证了：

• 单层块引用：以>引导的段落；
• 嵌套块引用：>逐级叠加即可形成多层嵌套（文件演示到了第三层）。

源码对应MarkdownBlockQuote（src/textual/widgets/_markdown.py），其默认样式为$boost背景色加左侧粗边框（border-left: outer $text-primary 50%），并为浅色终端单独设置了:light变体；嵌套引用的子级还会额外增加左边距（MarkdownBlockQuote > BlockQuote { margin-left: 2; }），在视觉上形成清晰的层级缩进。

表格：以 Rich Table 呈现并支持固定行列

example.md的 Tables 一节演示了 GFM 风格表格语法，并说明表格以 Rich table 渲染，参数表格示例包含show_header、fixed_rows、fixed_columns、zebra_stripes、header_height、show_cursor六个属性（见 examples/example.md）：

该表格实质上对应 Textual 的DataTable组件能力。在原文档中，作者同样以规划口吻提到"未来可能加入 CSV 导出与点击表头排序"——这些属于未实现的功能构想，引用时应注意区分现状与规划。

扩展：Markdown 与 MarkdownViewer 的关系

example.md的所有演示最终都由MarkdownViewer统一承载。理解两者的分工，有助于你决定在自己应用中选用哪个组件：

• Markdown：核心渲染组件，负责解析 Markdown 字符串/片段并将其转换为一系列MarkdownBlock子组件；支持update()全量替换与append()增量追加（src/textual/widgets/_markdown.py），还提供MarkdownStream用于流式追加文档（src/textual/widgets/_markdown.py）。
• MarkdownViewer：在Markdown之上封装目录侧边栏与浏览历史（src/textual/widgets/_markdown.py），其compose()同时挂载Markdown文档组件和MarkdownTableOfContents；go()/back()/forward()对应浏览器的前进后退体验，show_table_of_contents响应式属性控制目录显隐。

examples/markdown.py正是"组合两者"的典型范例：应用层只负责Footer+MarkdownViewer，目录开关、前进后退、按键禁用判断全部由MarkdownViewer的能力配合应用动作完成。

小结：example.md 透露的组件能力边界

结合examples/example.md的演示与 src/textual/widgets/_markdown.py 的实现，可以总结出 Textual Markdown 组件当前明确支持的能力清单：

• H1~H6 六级标题，且各级标题样式可通过设计令牌与 TCSS 覆写；
• 强调、加粗、删除线、行内代码四类行内排版；
• 水平分隔线；
• 有序/无序列表及多层嵌套，编号宽度自动对齐；
• 带语法高亮与缩进参考线的代码围栏（tree-sitter 驱动）；
• 单层与多层嵌套块引用；
• GFM 表格，支持固定行列、斑马纹等展示选项；
• 目录侧边栏、导航历史、流式追加等进阶能力由MarkdownViewer/MarkdownStream提供。

example.md的价值正在于此：它不是文档，而是"可运行的语法验收清单"。当你需要验证自己编写的 Markdown 能否被 Textual 完整呈现时，对照这份文件逐项检查，就能快速定位不支持或表现异常的语法。

• 前端
• UI组件
• 异步编程