企业官网建设流程全解析

presenterm 自定义介绍幻灯片实战：注释命令、列布局与图片排版指南

【免费下载链接】presentermA markdown terminal slideshow tool项目地址: https://gitcode.com/GitHub_Trending/pr/presenterm

本指南以 presenterm 仓库中的示例演示文件 custom-intro-slides.md 为核心素材，系统讲解如何用 HTML 注释形式的**注释命令（Comment Command）**打造三种风格各异的"自定义介绍幻灯片"：包括留白控制（newlines）、文本对齐（alignment）、幻灯片分隔（end_slide）、非等宽分栏（column_layout/column）以及内联 HTML 彩色文本。读完本文，你将能完全读懂并复用这份示例，在自己的 Markdown 演示中复刻出"图片 + 大标题 + 署名"的精致开场页。

示例文件定位与运行方式

该示例位于仓库的 examples/custom-intro-slides.md，与 demo.md、columns.md、footer.md 等共同构成示例演示集。根据 examples/README.md 的说明，本示例专门展示"包含图片、且图片被放置在不同布局中的多种自定义介绍幻灯片"。

本地运行方式：先安装 presenterm，再克隆本仓库，最后执行：

presenterm examples/custom-intro-slides.md

运行时按方向键翻页，即可依次看到三张介绍幻灯片。由于示例中用到了图片，建议在支持图片协议的终端（如 kitty、iTerm2、WezTerm、ghostty、foot 等）中运行以获得最佳效果。

示例速览：三张介绍幻灯片的三种排版

整份文件没有使用 front matter 或额外配置，全部效果均由"注释命令 + 标准 Markdown"组合完成，这也是它作为教学示例最有价值的地方。下面逐张拆解。

第一张：居中式（图片在上，标题居中）

<!-- newlines: 6 --> ![](doge.png) Custom introduction slides ==== <!-- alignment: center --> <span style="color: blue">John Doe</span> <!-- end_slide -->

这张幻灯片的构成要素：

• 文件第一行<!-- newlines: 6 -->在页面顶部预留 6 个单位行高的空白，把内容整体下压；
• ![](doge.png)引入柴犬图片（实际路径为 examples/doge.png），作为开场视觉元素；
• Custom introduction slides使用====一级标题语法，会以主题中的 slide title 样式渲染成醒目的演示标题；
• <!-- alignment: center -->让其后（直到幻灯片结束）的文本水平居中；
• <span style="color: blue">John Doe</span>以蓝色内联文本渲染演讲者署名；
• <!-- end_slide -->明确结束本张幻灯片，开始下一张。

第二张：左图右文（1:3 分栏）

<!-- newlines: 12 --> <!-- column_layout: [1, 3]--> <!-- column: 0 --> ![](doge.png) <!-- column: 1 --> <!-- newlines: 3 --> Custom introduction slides ==== <!-- alignment: center --> <span style="color: blue">John Doe</span> <!-- end_slide -->

这张幻灯片把页面拆成左右两栏：左侧占1份宽度放置图片，右侧占3份宽度放置标题与署名。同时用<!-- newlines: 12 -->在顶部预留更大留白，右侧再用<!-- newlines: 3 -->将标题下移，形成"上留白 + 右文左图"的经典杂志式版式。

第三张：左文右图（3:1 分栏）

<!-- newlines: 12 --> <!-- column_layout: [3, 1]--> <!-- column: 0 --> <!-- newlines: 3 --> Custom introduction slides ==== <!-- alignment: center --> <span style="color: blue">John Doe</span> <!-- column: 1 --> ![](doge.png)

第三张是第二张的镜像版：栏位比例换成[3, 1]，文字在左、图片在右，且文件末尾省略了end_slide（演示文件结束时自动收尾）。对比第二、三张可以看出，只需调整column_layout中的比例数字，就能在"图左文右"与"文左图右"之间自由切换。

驱动一切的机制：注释命令（Comment Command）

以上所有<!-- ... -->注释并不是普通 Markdown 注释，而是 presenterm 自定义的"注释命令"。presenterm 用 HTML 注释作为指令载体，是因为这类注释既能被 Markdown 解析器识别、又不会污染正文渲染，是表达"纯 Markdown 无法描述的行为"的轻量方案。

命令的解析入口与完整清单

命令解析集中在 src/presentation/builder/comment.rs：

• process_comment是总入口：先按配置中的命令前缀（command_prefix）裁剪注释内容，再交给CommentCommand枚举解析；
• CommentCommand枚举覆盖了全部命令，包括本示例用到的NewLines、Alignment、EndSlide、InitColumnLayout（即column_layout）、Column，以及其他命令如Pause、FontSize、JumpToMiddle、Include、IncrementalLists、NoFooter、SkipSlide、SpeakerNote、ResetLayout等；
• 注释内容通过serde_yaml反序列化（FromStr实现），因此命令携带参数时采用 YAML 风格语法，例如newlines: 6、column_layout: [1, 3]、alignment: center。

命令行快速查阅

不必翻文档，直接运行以下命令即可列出所有可用命令（含参数示例）：

presenterm --list-comment-commands

也可配合管道过滤，例如：

presenterm --list-comment-commands | grep alignment

输出形如：

<!-- alignment: left --> <!-- alignment: center --> <!-- alignment: right --> <!-- column_layout: [1, 2] --> <!-- column: 0 --> <!-- newlines: 2 --> <!-- new_line --> <!-- end_slide --> <!-- pause --> <!-- reset_layout --> ...

普通注释会被忽略

不是所有注释都会被当作命令。从 comment.rs 的should_ignore_comment实现可以看到，多行注释、不以命令前缀开头的注释、vim:开头的注释、//开头的注释以及{{{、}}}折叠标签等都会被安全忽略，不会导致构建失败。因此把个人备注、TODO 随手写成普通注释不会影响演示。

控制留白：newlines 命令的语义与实现

Markdown 规范本身会折叠连续的空白行，所以"我想在页面上留出 12 行空隙"这类需求无法用普通空行表达，这正是newlines命令存在的意义。

语法与语义

<!-- newlines: 6 --> <!-- 插入 6 个单位行高的空白 --> <!-- new_line --> <!-- 别名 newline，插入 1 个单位行高 -->

从源码看，NewLines(count)命令的处理逻辑是：

CommentCommand::NewLines(count) => { self.push_line_breaks(count as usize * self.slide_font_size() as usize); } CommentCommand::NewLine => self.push_line_breaks(self.slide_font_size() as usize),

即空白高度 = 参数值 × 当前字号行高：字号越大，单个newline单位占的行越高；如果某张幻灯片通过<!-- font_size: 2 -->放大了字号，同样的newlines: 6会留出更高的空白。这是理解示例中"顶部留白多少"的关键——示例第一行<!-- newlines: 6 -->表示留出约 6 行默认行高的高度。

在示例中的三种用法

• 文件首行<!-- newlines: 6 -->：把第一张幻灯片整体下移；
• 第二、三张的<!-- newlines: 12 -->：因为分栏后内容区更高，留白也相应加大；
• 第二、三张右（左）栏内的<!-- newlines: 3 -->：把标题从栏顶往下推 3 个单位，与图片形成垂直错落。

居中与对齐：alignment 命令

alignment命令用于控制"当前幻灯片剩余部分"的文本水平对齐方式，可选值为left、center、right：

<!-- alignment: left --> 左对齐（默认） <!-- alignment: center --> 居中 <!-- alignment: right --> 右对齐

对应源码在 comment.rs 的Alignment分支，将解析结果映射为Alignment::Left、Alignment::Center、Alignment::Right三种主题对齐模式（Center 还支持minimum_margin、minimum_size等附加参数，可被主题覆盖）。本示例中alignment: center之后紧跟<span style="color: blue">John Doe</span>，使署名相对整屏水平居中，配合上方居中的大标题形成对称构图。

提示：alignment与列布局可以叠加使用。在第二张幻灯片的第 1 列内先newlines: 3再alignment: center，居中是相对该列的有效宽度计算的，而不是整屏，这与直觉一致。

分栏排版：column_layout 与 column

比例即宽度

column_layout用一组正整数定义分栏，数字总和代表整屏宽度被均分成的"份数"，每个数字代表对应列占据的份数：

<!-- column_layout: [1, 3] --> <!-- 共 4 份：左列占 25%，右列占 75% --> <!-- column_layout: [3, 1] --> <!-- 共 4 份：左列占 75%，右列占 25% --> <!-- column_layout: [1, 2, 1] --><!-- 共 4 份：三列，中间列占 50% -->

因此示例第二张是"图占 25%、文占 75%"，第三张则是"文占 75%、图占 25%"。

进入列与退出

定义布局后，用column命令声明后续内容进入哪一列：

<!-- column: 0 --> <!-- 进入第 0 列（最左列） --> <!-- column: 1 --> <!-- 进入第 1 列 -->

从源码看，builder 内部通过LayoutState状态机跟踪布局：Default（无布局）→InLayout（已定义布局）→InColumn（已进入某列）。InitColumnLayout会生成RenderOperation::InitColumnLayout渲染操作并记录布局网格与边距（column_layout.margin主题项可配置列间距）；EnterColumn对应切换列。离开列的三种方式：

• 用<!-- column: N -->切换到另一列（内容写入新列）；
• 用<!-- reset_layout -->重置布局，之后的内容回到整屏宽度（位于所有列下方）；
• 遇到<!-- end_slide -->，幻灯片结束，布局随之终止。

合法性与错误校验

comment.rs 中内置了大量边界校验，并在同文件测试用例中得到验证，例如：

• 未先声明column_layout就使用column会报NoLayout错误（对应测试layout_without_init）；
• column_layout: []、[0]、[1, 0]这类空布局或含零值宽度的布局是非法的（对应测试invalid_layouts）；
• 重复进入同一列会报AlreadyInColumn（对应测试already_in_column）；
• 列索引超出布局列数会报ColumnIndexTooLarge（对应测试column_index_overflow）。

这些校验保证布局状态机不会产生歧义渲染。同一列内的内容支持来回跳转填充（测试columns_back_and_forth验证了"先写第 0 列再写第 1 列再回到第 0 列"的场景），因此你可以按任何顺序组织各列内容。

column_layout分栏的实际渲染效果可参考 layouts.png（来自官方文档 layout.md 的 2:1 分栏示例）：

另一种玩法：用分栏实现局部居中

column_layout不止用于并排内容。如果想让某段内容在水平方向"居中占据约 60% 宽度"，可以定义[1, 3, 1]三栏布局，只往中间栏写内容，左右各留 1 份空白——这是官方文档 layout.md 明确推荐的做法，也是自定义介绍幻灯片排版时的常用技巧。

内联 HTML：给署名上色

示例中<span style="color: blue">John Doe</span>使用了内联 HTML。presenterm 的 Markdown 解析基于 comrak（见 src/markdown/parse.rs），内联 HTML 标签会被解析为内联元素并参与渲染，因此可以用<span style="color: ...">等方式为局部文本着色。注意：

• 该能力定位是"轻量点缀"，presenterm 并不支持用 HTML 写复杂布局（这也是它引入column_layout注释命令而非依赖 div 的原因，详见 layout.md 中的说明）；
• 更规范的做法是把颜色放进主题（themes）中统一管理，内联样式适合示例这种"随手演示"的场景。

图片支持前提

示例大量使用![](doge.png)这类引用图片，其最终显示效果取决于终端能力：

• 在支持图片协议的终端（kitty、iTerm2、WezTerm、ghostty、foot 等）上会以真实图片渲染（examples/README.md 指出 asciinema 录屏中图片呈像素化，正是录制工具不支持图片协议所致）；
• presenterm 内部实现了多种图片协议与回退策略，相关代码位于 src/terminal/image/；
• 示例中的图片路径doge.png相对于演示文件所在目录解析，即 examples/doge.png；你的演示中引用图片时同样遵循"相对当前 Markdown 文件"的规则。

关键源码与文档地图

• 注释命令核心实现与全部命令定义：src/presentation/builder/comment.rs（含大量布局/对齐/换行的行为测试）
• 注释命令总览文档：docs/src/features/commands.md
• 列布局完整用法（比例机制、reset_layout、局部居中技巧）：docs/src/features/layout.md
• 图片显示与终端支持：docs/src/features/images.md
• 其他示例演示：examples/README.md

掌握本示例所涉及的newlines、alignment、column_layout、column、end_slide五类注释命令之后，你就能像搭积木一样组合出任意版式的开场页：无论是一张图配大标题的极简风格，还是左图右文、左文右图的杂志风格，都只需调整几行注释命令即可完成，无需任何外部工具或模板。

【免费下载链接】presentermA markdown terminal slideshow tool项目地址: https://gitcode.com/GitHub_Trending/pr/presenterm