presenterm 主题文件完全指南从对齐、颜色、页脚到调色板的 YAML 主题定义【免费下载链接】presentermA markdown terminal slideshow tool项目地址: https://gitcode.com/GitHub_Trending/pr/presentermpresenterm终端 Markdown 幻灯片工具允许通过 YAML 主题文件精细控制每张幻灯片的渲染外观。本文以官方主题定义文档为主体结合仓库源码src/theme/raw.rs、src/theme/clean.rs、src/theme/registry.rs与内置主题themes/dark.yaml 等系统讲解主题文件的根元素结构、对齐方式、颜色体系、开场页、页脚、标题/标题层级、代码块高亮、引用块、Mermaid、告警、主题继承与调色板等全部配置项。读完本文你将能够从零编写、继承并调试一套属于你自己的 presenterm 主题。主题文件的整体结构根元素主题文件是一个纯 YAML 文件。按照官方文档的说明主题文件的根属性root attributes只承担两种职责指定输入 Markdown 或渲染后演示文稿中的某一类具体元素例如幻灯片标题slide_title、各级标题headings、页脚footer、代码块code等提供一个默认值default当某个元素没有指定自己的样式时作为回退样式兜底使用。从源码看主题的完整字段集合定义在 src/theme/raw.rs#L17-L105 的PresentationTheme结构体中并且该结构体标注了#[serde(deny_unknown_fields)]——也就是说任何不在白名单里的顶层字段都会导致主题加载失败这有助于在编写主题时及早发现拼写错误。完整的顶层字段包括顶层字段作用extends继承的其他主题名内置或自定义default全局默认样式margin colors alignmentslide_title幻灯片标题样式headingsh1 ~ h6 各级标题样式code代码块样式含语法高亮主题inline_code行内代码样式execution_output/pty_output代码执行输出、PTY 交互输出的样式bold/italics粗体 / 斜体文字的配色table表格对齐方式block_quote/alert引用块 / GitHub 风格告警样式column_layout多列布局的列间距intro_slide开场页各元素样式footer页脚模板 / 进度条 / 空typst/mermaid/d2三类自动渲染代码块的样式modals/layout_grid弹窗、布局网格样式palette调色板预定义颜色与 class这些字段大多可以省略源码中均有#[serde(default)]省略时使用内置默认值。对齐Alignmentpresenterm 借鉴了 GUI 编辑器的“对齐”概念可以将文字对齐到终端屏幕的左、中、右。官方文档的建议是大多数元素左对齐、部分元素居中对齐、一般不需要右对齐当然你也可以这么做。支持对齐的元素包括代码块code幻灯片标题slide_title开场页中的标题、副标题和作者intro_slide的title/subtitle/author表格table。从源码 src/theme/raw.rs#L402-L429 看Alignment是一个带alignment标签的枚举分为left、right、center三种变体其默认值是left且margin: fixed: 0。左/右对齐与 margin左对齐和右对齐都接受一个margin属性表示文本与终端屏幕左/右边框之间保留的列数。margin有两种写法固定值Fixed——无论终端多宽都保留固定字符数alignment: left margin: fixed: 5百分比Percent——按终端总列数的一定百分比计算alignment: left margin: percent: 8官方文档特别指出百分比对齐通常观感更好因为终端尺寸变化时它不会过多改变演示文稿的整体外观。源码中百分比的计算方式是ceil(终端列数 × percent / 100)见 src/theme/raw.rs#L795-L804 的Margin::as_characters即向上取整。居中与 minimum_size / minimum_margin居中对齐有两个属性minimum_size元素的最小尺寸列数。这对代码块尤其有用因为代码块带有预定义的背景色你通常希望背景在代码右端之外再多延伸一点minimum_margin最小边距结构上与左/右对齐的margin相同。它指定了文本左右两侧至少要保留的列数。官方文档提醒它和minimum_size一起用效果不太好但单独使用时它定义了文本两侧的最小列数。在 src/theme/clean.rs#L496-L503 中居中对齐通过size.max(minimum_size)来调整元素的最终宽度印证了minimum_size是“至少为多大”的下限语义。颜色Colors每个元素都可以通过colors键指定自己的前景色foreground和背景色background颜色使用hex 十六进制记法default: colors: foreground: ff0000 background: 00ff00从源码 src/theme/raw.rs#L932-L968 的RawColor::from_str可以看到完整的颜色解析规则支持3 位或 6 位 hex3 位会自动展开成 6 位如f00→ff0000也支持16 种命名颜色black、white、grey、dark_grey、red、dark_red、green、dark_green、blue、dark_blue、yellow、dark_yellow、magenta、dark_magenta、cyan、dark_cyan还支持调色板引用palette:name或p:name见下文“调色板”小节如果 hex 长度既不是 3 也不是 6会直接报错。default 默认样式default是整个主题的“地基”它指定两件事应用到所有幻灯片的边距margin用于所有文字的前景色与背景色。default: margin: percent: 8 colors: foreground: e6e6e6 background: 040312除此之外从 src/theme/raw.rs#L349-L361 可以看到default还支持一个alignment字段通过flatten展开作为段落、列表等未单独指定对齐方式的元素的兜底对齐。内置的 themes/dark.yaml 正是以margin: percent: 8 前景色palette:white、背景色040312开头。开场页Intro Slide当演示文稿的 front matter 中指定了title、sub_title或author时presenterm 会渲染一个“不那么 Markdown 味”的开场页避免整场演示显得单调--- title: Presenting from my terminal sub_title: Like its 1990 author: John Doe ---主题中的intro_slide键可以为这些元素分别指定样式title、subtitle可指定对齐方式和颜色author可指定对齐方式、颜色以及定位方式positioningpage_bottom把作者推到屏幕底部below_title把作者放在标题若有副标题则放在副标题正下方。例如intro_slide: title: alignment: left margin: percent: 8 author: colors: foreground: black positioning: below_title从源码看intro_slide实际还支持event、location、date等行内元素的样式src/theme/raw.rs#L316-L345 的IntroSlideStyle以及一个footer: false开关来禁用开场页的页脚。在 themes/dark.yaml 中可以看到一个完整的开场页配置示例标题居中、字号 2、作者居中且positioning: page_bottom、footer: false。若要了解开场页各字段的完整用途可结合 主题简介 与演讲文档中的 front matter 说明一起阅读。页脚Footer页脚目前有三种风格style字段区分对应源码 src/theme/raw.rs#L454-L488 中的FooterStyle枚举template、progress_bar、empty。模板页脚Template模板页脚允许在屏幕的左、中、右三个位置放置文本。模板字符串中可以引用两个特殊变量{current_slide}当前页码{total_slides}总页数。除此之外front matter 中定义的所有属性也都可以引用titlesub_titleeventlocationdateauthor模板字符串本身可以包含任意 Markdown包括span标签配合下文“调色板”中的 class 即可实现彩色文字。height属性用于指定页脚的高度以终端行数为单位页脚中的文字始终放置在页脚区域的垂直居中位置。footer: style: template left: My **name** is {author} center: _myhandle_ right: {current_slide} / {total_slides} height: 3官方文档明确了两条使用注意点只能引用 front matter 中真实存在的属性。例如引用了{date}但 front matter 里没有设置date就会报错引用不支持的变量如{potato}也会报错。如果你确实需要输出{}这样的字面字符需要用双括号转义{{potato}} farms会显示为{potato} farms。源码 src/theme/raw.rs#L568-L670 的FooterTemplate::from_str完整实现了这套模板解析它逐字符扫描遇到{{输出一个字面{遇到}时把中间内容与current_slide、total_slides、author、title、sub_title、event、location、date逐一比对命中不了的变量会产生ParseFooterTemplateError::UnsupportedVariable错误同时还会校验“嵌套{”“未闭合{”“无匹配的}”等语法错误。另外模板页脚还支持colors键为整条页脚设置颜色src/theme/raw.rs#L466-L471。仓库中的 examples/footer.md 是一个可直接运行的页脚示例它在 front matter 中通过theme.override定义了包含图片、加粗文字、span classnoice彩色文字与页码变量的模板页脚。渲染效果见下图页脚图片除了文字页脚的左/中/右位置还可以放图片方法是在对应属性下指定image键footer: style: template left: image: potato.png center: image: banana.png right: image: apple.png # 页脚高度用于调整图片尺寸 height: 5图片的查找顺序是先相对于演示文稿文件查找和普通图片一样找不到时再相对于主题目录查找例如~/.config/presenterm/themes。这样你就可以在主题目录里定义一个引用同目录本地图片的自定义主题。图片会保持宽高比并在垂直方向扩展占满footer.height指定的行数。因此如果页脚使用了“高大于宽”的图片需要相应调大height参数。从源码看页脚内容的解析src/theme/raw.rs#L511-L560把字符串与{image: path}映射结构都收编为FooterContent图片最终通过resources.theme_image(path)解析src/theme/clean.rs#L576-L586。关于页脚高度默认值需要特别说明官方文档标注的默认高度为 2而当前仓库源码 src/theme/clean.rs#L15 中定义的DEFAULT_FOOTER_HEIGHT为 3具体渲染以你使用的版本实际行为为准。进度条页脚Progress Bar进度条页脚会随着你在演示中翻页而前进。默认使用一个**方块字符█**绘制进度条但你可以自定义字符footer: style: progress_bar # 可选 character: 源码中DEFAULT_PROGRESS_BAR_CHAR就是█src/theme/clean.rs#L14同时该风格也支持colors键设置颜色。无页脚None如果你完全不想要页脚footer: style: empty幻灯片标题Slide Title通过 setext 语法在标题下一行写指定的幻灯片标题可以这样定制slide_title: # 标题前缀。 prefix: ██ # 字号终端支持时生效。 font_size: 2 # 标题上方垂直内边距。 padding_top: 1 # 标题下方垂直内边距。 padding_bottom: 1 # 是否在标题后绘制一条水平分隔线。 separator: true # 是否使用粗体。 bold: true # 是否使用下划线。 underlined: true # 是否使用斜体。 italics: true # 颜色。 colors: foreground: beeeff background: feeeddslide_title还支持alignment如 themes/dark.yaml 中设为center。从源码 src/theme/clean.rs#L29-L31 看font_size会被 clamp 到1 ~ 7之间并且只有终端支持字号调整时才生效否则一律按 1 处理。标题层级Headingsh1 到 h6 每一级标题都可以拥有独立样式可配置的属性包括prefix标题前缀字符串colors前景/背景色bold/underlined/italics是否加粗、下划线、斜体alignment、font_size对齐方式与字号见 src/theme/raw.rs#L190-L221。headings: # H1 样式。 h1: # 标题前缀。 prefix: ██ # 颜色。 colors: foreground: beeeff background: feeedd # 是否粗体。 bold: true # 是否下划线。 underlined: true # 是否斜体。 italics: true # H2 样式键与 H1 相同。 h2: prefix: ▓▓▓ colors: foreground: feeedd内置主题里可以看到非常生动的用法themes/dark.yaml 为 h1 ~ h6 依次使用了██、▓▓▓、▒▒▒▒、░░░░░等不同长度的块状字符作为前缀并在各级标题上搭配不同颜色形成清晰的视觉层级。代码块Code Blocks代码块的语法高亮由 syntect 可以看到语法集与高亮主题集分别由仓库bat/目录下的syntaxes.bin、themes.bin二进制文件在编译期嵌入运行时再按需反序列化加载。内置支持的高亮主题列表如下base16-ocean.darkbase16-eighties.darkbase16-mocha.darkbase16-ocean.lightCatppuccinColdarkDarkNeonInspiredGitHubNord-sublimeSolarizedSolarized (dark)Solarized (light)TwoDarkdracula-sublimegithub-sublime-themegruvboxonehalfsublime-monokai-extendedsublime-snazzyvisual-studio-dark-pluszenburn其中大部分主题来源于 bat 工具官方文档特别向 bat 的作者们致谢。代码块本身还有几个额外的属性code: # 代码高亮主题名。 theme_name: base16-eighties.dark # 代码片段周围的单元格内边距。 padding: horizontal: 2 vertical: 1 # 是否在代码块周围使用该高亮主题的背景色。 background: false # 是否默认给所有代码片段显示行号。 line_numbers: false补充几个源码确认的默认行为src/theme/clean.rs#L588-L612theme_name的默认值是base16-eighties.darkDEFAULT_CODE_HIGHLIGHT_THEMEbackground的默认值是true使用主题背景色line_numbers默认 falsecode同样支持alignment含居中所需的minimum_size/minimum_margin。自定义高亮主题除了内置高亮主题你可以把任意.tmTheme主题文件放到配置目录下的themes/highlighting子目录中例如 Linux 下的~/.config/presenterm/themes/highlightingpresenterm 启动时会自动加载它们。加载逻辑位于 src/code/highlighting.rs#L58-L70 的HighlightThemeSet::register_from_directory它直接调用 syntect 的ThemeSet::load_from_folder扫描目录下的.tmTheme文件。配置目录的具体位置见 配置介绍Linux 为$XDG_CONFIG_HOME/presenterm/未定义该变量时是~/.config/presenterm/macOS 为~/Library/Application Support/presenterm/Windows 为~/AppData/Roaming/presenterm/config/。引用块Block Quotes引用块可以指定一个字符串作为引用文本每一行的前缀block_quote: prefix: ▍ 源码中该前缀的默认值就是▍ DEFAULT_BLOCK_QUOTE_PREFIX见 src/theme/clean.rs#L13。block_quote还支持colors前景/背景以及一个额外的colors.prefix来单独给前缀着色src/theme/raw.rs#L243-L251并支持alignment。Mermaid 图表Mermaid 图表可以通过以下参数定制mermaid.background传给 CLI 的背景色例如transparent、red、#F0F0F0mermaid.theme使用的 Mermaid 主题。mermaid: background: transparent theme: dark源码中两者的默认值分别是default与transparentsrc/theme/clean.rs#L18-L19。关于 Mermaid 代码块的使用方式可参考 Mermaid 功能文档。GitHub 风格告警AlertsGitHub 风格的 Markdown 告警alert可以通过alert键定制alert: # 告警内所有文字的基础颜色。 base_colors: foreground: red background: black # 告警每一行的前缀。 prefix: ▍ # 每种告警类型的样式。 styles: note: color: blue title: Note icon: I tip: color: green title: Tip icon: T important: color: cyan title: Important icon: I warning: color: orange title: Warning icon: W caution: color: red title: Caution icon: C源码 src/theme/clean.rs#L311-L374 为五种类型分别提供了默认的标题与图标如 Note / Tip / Important / Warning / Caution 以及对应的 unicode 图标color、title、icon未指定时都会回退到这些默认值base_colors作为整块文字的基础样式。主题继承Extends自定义主题可以继承其他自定义主题或内置主题默认继承被继承主题的全部属性。例如extends: dark default: colors: background: 000000这个主题继承了内置的dark主题并把背景色覆盖为000000。官方文档指出这特别适合“几乎喜欢某个内置主题但只有个别属性不满意”的场景。从源码看继承机制比表面更讲究加载目录时src/theme/registry.rs#L90-L123 会构建一个依赖图ThemeGraph先处理“就绪”基类是内置主题的主题再逐步处理依赖自定义主题的派生主题派生主题通过merge_struct::merge与基类主题做深度合并src/theme/registry.rs#L69-L80因此你只需写出要覆盖的键若extends指向一个不存在的主题会报ExtendedThemeNotFound若主题之间存在循环继承如 A 继承 B、B 继承 A会报ExtensionLoop错误内置主题本身不允许使用extends见 src/theme/registry.rs#L160-L177 的测试注释测试用例 src/theme/registry.rs#L198-L237 验证了多级继承链与循环检测的行为。调色板Color palette每个主题都可以定义一个调色板包含两部分colors一组预定义颜色classes一组前景/背景色对称为 class。颜色和 class 都可以在spanHTML 标签里用来给文字着色颜色还可以在主题内部各处引用避免同一个 hex 值在主题定义里反复出现。palette: colors: red: f78ca2 purple: 986ee2 classes: foo: foreground: ff0000 background: 00ff00调色板颜色可以通过palette:name或p:name引用。现在主题里任何需要颜色的地方都可以写p:red、p:purplespan stylecolor: palette:redthis is red/span span classfoothis is foo-colored/span这些颜色可以在演示文稿的任何位置使用也可以用在模板页脚和开场页中。有几个源码层面的细节值得注意palette.colors里的每一项必须是直接的颜色值不允许再引用其他调色板颜色否则报PaletteColorInPalette错误见 src/theme/clean.rs#L855-L883class 的foreground/background可以引用colors中定义的颜色解析阶段src/theme/raw.rs#L906-L924会把palette:name、p:name以及 class 引用统一解析为最终Color若引用了未定义的颜色会报UndefinedPaletteColorError。在 themes/catppuccin-mocha.yaml 中可以看到一个完整调色板的范例——它把整个 Catppuccin 色板rosewater、flamingo、mauve、teal、sky、sapphire 等 26 个颜色定义在palette.colors下主题的每一处颜色都通过palette:name引用既避免重复又便于整体换色。粗体/斜体样式默认情况下粗体和斜体文字不会获得任何额外颜色。顶层bold与italics键可以为它们定义一套颜色bold: colors: foreground: red italics: colors: background: blue注意源码里italics字段还兼容italic这个别名src/theme/raw.rs#L47-L48。这套颜色适用于所有使用粗体/斜体的文本。实战从零编写并加载自定义主题把以上知识串起来编写一个自定义主题的完整流程如下放置位置把.yaml文件放到配置目录下的themes/目录如 Linux 的~/.config/presenterm/themes/。启动时 src/theme/registry.rs#L28-L67 会扫描该目录文件名去掉.yaml后缀即主题名加载后与内置主题一视同仁可用于--theme参数、front matter 的theme.name等。若自定义主题名与内置主题重名会报Duplicate错误。选择继承或从零先extends: dark或任意内置主题做增量覆盖效率最高也可以完全不写extends从default样式开始逐项定义。写全你关心的元素参考 themes/dark.yaml 的结构——default打底、slide_title与headings建立标题层级、code选高亮主题与内边距、intro_slide美化开场页、footer选页脚风格、palette统一管理颜色。验证用presenterm --list-themes可以快速预览所有内置主题的渲染效果相关内容见 主题简介也可以直接在演示文稿 front matter 里用theme.override临时覆盖主题做快速迭代examples/footer.md 就是这种用法。利用配置目录扩展语法高亮主题放在配置目录的themes/highlighting/下配置文件本体放在配置目录根部的config.yaml详见 配置介绍。理解这套主题体系的关键在于把握三个层次默认样式兜底default、逐元素覆盖slide_title、headings、code等、调色板统一取色palette。掌握了它们你就能精确控制 presenterm 幻灯片中的每一个视觉细节。【免费下载链接】presentermA markdown terminal slideshow tool项目地址: https://gitcode.com/GitHub_Trending/pr/presenterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考