presenterm 主题体系完全指南内置主题选择、Front Matter 配置与自定义主题文件编写【免费下载链接】presentermA markdown terminal slideshow tool项目地址: https://gitcode.com/GitHub_Trending/pr/presentermpresenterm 是一个用 Markdown 驱动终端幻灯片演示的工具它把主题设计成了一套完整、可深度定制的 YAML 样式体系既内置了多套开箱即用的配色方案也允许你通过 CLI 参数、演示文稿 front matter 或本地主题目录三种途径加载与覆盖主题。读完本文你将掌握--theme、theme.name、theme.path、theme.override的全部用法能看懂并独立编写一个完整的主题 YAML 文件含对齐、页脚模板、代码高亮、调色板、主题继承等全部要素并理解内置主题在源码中是如何被打包、解析与校验的。主题机制概述presenterm 的设计目标是尽可能可配置让每一份演示文稿都呈现出使用者想要的精确外观。整个主题机制由三部分构成内置主题随二进制一起打包的一组 YAML 主题无需任何外部文件即可使用自定义主题放置在配置目录themes子目录下的.yaml文件启动时自动加载使用方式与内置主题完全一致front matter 覆盖override在演示文稿自身的 Markdown front matter 中直接覆写主题的任意属性实现为这一份演示单独调样式。从源码看内置主题在编译期通过include!(concat!(env!(OUT_DIR), /themes.rs))嵌入二进制见 src/theme/registry.rs按需反序列化自定义主题则由PresentationThemeRegistry::register_from_directory在启动时扫描配置目录加载。两者最终都汇入同一个注册表由load_by_name统一查找。设置主题的四种方式presenterm 提供了多条设置主题的路径优先级与作用范围各不相同。方式一CLI 参数--theme运行 presenterm 时通过--theme参数指定一个主题名称内置或已加载的自定义主题均可这是最直接的方式presenterm --theme gruvbox-dark slides.md对应 CLI 定义见 src/main.rs/// The theme to use. #[clap(short, long)] theme: OptionString,同时支持短参数-t。通过 CLI 指定的主题会作为默认值但仍可被演示文稿 front matter 中显式声明的主题覆盖见下文。方式二front matter 按名称指定在演示文稿的 Markdown 文件头部写入 front matter 即可固定主题无论 CLI 默认值是什么该演示都会使用这里指定的主题--- theme: name: dark ---方式三front matter 按明暗模式区分presenterm 支持终端明暗色系的自动检测。你可以同时声明light与dark两套主题工具会根据终端当前使用的配色自动选择--- theme: # The theme used if your terminal is using light colors. light: light # The theme used if your terminal is using dark colors. dark: dark ---方式四front matter 按文件路径指定主题文件本质上就是一份 YAML你可以把它放在文件系统的任意位置然后通过path引用--- theme: path: /home/me/Documents/epic-theme.yaml ---从 src/presentation/builder/frontmatter.rs 的set_theme实现可以看出两条约束theme.name与theme.path不能同时出现否则报错 cannot set both theme.path and theme.name通过路径加载的主题若带有extends字段会先按名称解析其继承的基主题并合并再作为最终主题使用。另外还有一个--default-theme相关的force_default_theme选项当它被启用时front matter 中的name/path会被忽略强制使用默认主题。方式五front matter 覆写override如果只是想让某一份演示在现有主题基础上做局部调整不必复制整份主题文件直接在 front matter 中覆写即可--- theme: override: default: colors: foreground: beeeff ---这一机制有两个明显收益为单场演示定制独有风格省去复制主题 → 另存 → 修改的繁琐流程由于演示文件保存时内容会热重载overrides 随之重新加载你可以非常快速地迭代样式。在源码实现中override 会被merge_struct::merge合并到当前基础主题之上未指定name/path时合并到默认主题之上并且override内部不允许再出现extends字段见 frontmatter.rs 中 theme overrides cant use extends 的错误分支。内置主题一览presenterm 内置了十余套主题全部随二进制分发使用它们不需要任何外部文件。当前内置主题包括Catppuccin 配色系列基于 catppuccin 调色板catppuccin-lattecatppuccin-frappecatppuccin-macchiatocatppuccin-mochadark深色主题是许多自定义主题继承的默认基座gruvbox-dark灵感来自 gruvbox 配色的深色主题light浅色主题terminal-dark完全使用终端自身的配色适合终端背景为透明或图片的场景让演示融入终端外观terminal-light与terminal-dark相同但面向浅色终端配色TokyoNight 配色系列基于 tokyonight 调色板tokyonight-moontokyonight-daytokyonight-nighttokyonight-storm这些主题的源码就在仓库 themes 目录下例如 themes/dark.yaml 是 dark 主题的完整定义themes/catppuccin-mocha.yaml、themes/tokyonight-night.yaml 等均为可直接阅读、可复制改写的样例。前端定制时从这些现成文件出发是最快的上手路径。快速预览所有内置主题使用--list-themes参数可以一次预览全部内置主题的效果presenterm --list-themes该命令会生成一份特殊的演示文稿每一张幻灯片用不同的主题渲染同样的内容让你直观对比各主题的外观差异演示文稿中还包含对应主题的名称提示。对应的 CLI 实现见 src/main.rs/// List all supported themes. #[clap(long, group target)] list_themes: bool,此外还有--current-theme参数用于打印当前演示实际生效的主题名称方便排查为什么样式不是我预期的这类问题。加载自定义主题如果你不想用内置主题可以把自己的主题放进配置目录的themes子目录。presenterm 启动时会扫描该目录将其中所有.yaml文件注册为主题注册后它们与内置主题地位完全等价既可作为--theme的参数也可用于 front matter 的theme.name。配置目录的位置与 配置文件 相同按平台区分Linux~/.config/presenterm/或$XDG_CONFIG_HOME/presenterm/macOS~/Library/Application Support/presenterm/Windows~/AppData/Roaming/presenterm/config/因此 Linux 上自定义主题应放在~/.config/presenterm/themes/下例如mkdir -p ~/.config/presenterm/themes cp my-theme.yaml ~/.config/presenterm/themes/ presenterm --theme my-theme slides.md注意文件名去掉.yaml后缀即为主题名因此my-theme.yaml对应的主题名是my-theme。注册与校验的源码细节从 src/theme/registry.rs 的register_from_directory可以看到加载过程相当严谨只加载.yaml后缀的文件若自定义主题名与内置主题重名会报Duplicate错误每个主题会先被解析为PresentationTheme未知字段会被拒绝见 src/theme/raw.rs 中#[serde(deny_unknown_fields)]通过ThemeGraph处理extends继承链先解析被继承的主题再合并循环继承会报ExtensionLoop错误继承不存在的主题会报ExtendedThemeNotFound目录不存在时静默跳过视为无自定义主题不报错。仓库测试用例覆盖了上述全部路径load_custom验证自定义主题继承dark后与dark内容一致load_derive_chain验证多级继承链 A→dark、B→C→A 能正确解析invalid_derives与load_derive_chain_loop分别验证了继承不存在的主题与A↔B 循环继承会报错。主题文件结构详解主题文件就是一份 YAML顶层键分为两类一类是 Markdown 输入或渲染结果中的具体元素幻灯片标题、各级标题、页脚等另一类是作为兜底回退的default默认样式。下面按元素逐一讲解完整示例可对照 themes/dark.yaml 阅读。对齐Alignmentpresenterm 使用与 GUI 编辑器类似的对齐概念支持左对齐、居中和右对齐。绝大多数元素适合左对齐部分元素适合居中。支持对齐的元素包括代码块、幻灯片标题、intro slide 中的标题/副标题/作者、表格。左/右对齐使用margin指定文本与终端屏幕边缘之间保留的列数margin有两种写法固定值无论终端多宽都保留固定列数alignment: left margin: fixed: 5百分比按终端总列数的一定比例计算alignment: left margin: percent: 8百分比方式在终端尺寸变化时对整体观感影响更小通常视觉效果更好。其计算逻辑在 src/theme/raw.rs 的Margin::as_charactersPercent(p)会换算为(screen_size * p / 100).ceil()列。居中对齐有两个属性minimum_size元素的最小宽度列数。对代码块这类自带背景色的元素尤其有用——你通常希望背景色向右稍微超出代码末尾minimum_margin最小边距结构与margin相同表示文本左右至少保留多少列。它与minimum_size一般不同时使用。对齐的枚举定义见 src/theme/raw.rs默认对齐为Left { margin: Fixed(0) }。颜色Colors每个元素都可以用十六进制 RGB 指定自己的前景色/背景色default: colors: foreground: ff0000 background: 00ff00十六进制颜色支持 6 位如ff0000与 3 位缩写如f00会被展开为ff0000同时也支持一组命名颜色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。颜色解析逻辑见 src/theme/raw.rs 的RawColor::from_str仓库测试color_serde验证了beef42与 3 位缩写ded展开为ddeedd的解析往返。默认样式Default styledefault键定义全局兜底样式应用于所有幻灯片的边距所有文本默认使用的颜色。default: margin: percent: 8 colors: foreground: e6e6e6 background: 040312Intro Slide开场幻灯片当演示文稿 front matter 中声明了title、sub_title或author时presenterm 会渲染一张区别于普通 Markdown 排版的 intro slide避免开场页显得单调--- title: Presenting from my terminal sub_title: Like its 1990 author: John Doe ---front matter 还可声明event、location、date等字段它们也会出现在 intro slide 上。主题中可对 intro slide 的各个元素单独设置title / subtitle对齐方式与颜色author对齐、颜色以及定位方式positioning——page_bottom把作者推到屏幕底部below_title则放在标题或副标题正下方此外还可为 intro slide 关闭页脚footer: false。intro_slide: title: alignment: left margin: percent: 8 author: colors: foreground: black positioning: below_titleAuthorPositioning枚举定义于 src/theme/raw.rs默认值为page_bottom其渲染行为见 frontmatter.rs 的push_intro_slidebelow_title会在作者前插入 3 个空行page_bottom则直接跳到屏幕底部行。页脚Footer页脚有三种风格template模板、progress_bar进度条、empty无页脚。模板页脚模板页脚允许在屏幕左侧、中间、右侧分别放置文本。模板字符串中可以引用{current_slide}与{total_slides}两个特殊变量分别替换为当前页码与总页数。除此之外front matter 中声明的任何属性都可以作为变量引用{title}{sub_title}{event}{location}{date}{author}模板字符串本身支持任意 Markdown包括用span标签实现彩色文字。height属性指定页脚区域占用的终端行数文本始终在页脚区域内垂直居中默认高度为 2。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 的FooterTemplate::from_str中实现它把字符串切分为字面量与变量块支持的双花括号转义、以及NestedOpenBrace、TrailingBrace、ClosedBraceWithoutOpen、UnsupportedVariable四类错误都由同一文件中的单元测试parse_all_footer_template_variables、parse_double_braces、invalid_footer_templates覆盖验证。页脚中的图片除了文字模板页脚的左/中/右位置还可以放图片通过image键指定footer: style: template left: image: potato.png center: image: banana.png right: image: apple.png # The height of the footer to adjust image sizes height: 5图片的查找顺序是先相对演示文稿文件所在目录查找与普通图片一致找不到时再相对主题目录如~/.config/presenterm/themes查找——这样你就可以在主题目录里定义一个指向同目录本地图片的自定义主题。图片会保持宽高比并纵向扩展填满footer.height指定的行数如果页脚中使用了高大于宽的图片应相应调大height。仓库中 examples/footer.md 提供了一个同时包含图片与彩色文字的页脚示例效果如下图所示。进度条页脚进度条页脚会随着演示翻页而推进默认使用方块字符绘制也可自定义字符footer: style: progress_bar # Optional! character: 无页脚footer: style: emptyFooterStyle枚举Template/ProgressBar/Empty的定义与默认值无内容、高度为空的模板页脚见 src/theme/raw.rs。幻灯片标题Slide Title幻灯片标题使用 setext 标题语法产生可以这样定制slide_title: # The prefix to use for the slide title. prefix: ██ # The font size to use. font_size: 2 # The vertical padding added before the title. padding_top: 1 # The vertical padding added after the title. padding_bottom: 1 # Whether to use a horizontal separator line after the title. separator: true # Whether to style for the title using bold text. bold: true # Whether to style for the title using underlined text. underlined: true # Whether to style for the title using italics text. italics: true # The colors to use. colors: foreground: beeeff background: feeedd其中font_size只在终端支持时生效separator控制标题后是否绘制一条水平分隔线。各级标题Headingsh1 到 h6 每一级都可以拥有独立的样式可用属性包括前缀、颜色、粗体/下划线/斜体、字号与对齐headings: # H1 style. h1: # The prefix to use for the heading prefix: ██ # The colors to use. colors: foreground: beeeff background: feeedd # Whether to style for the title using bold text. bold: true # Whether to style for the title using underlined text. underlined: true # Whether to style for the title using italics text. italics: true # H2 style, same as the keys for H1. h2: prefix: ▓▓▓ colors: foreground: feeedd在 themes/dark.yaml 中可以看到一套完整的 h1~h6 前缀设计h1 用██、h2 用▓▓▓、h3 用▒▒▒▒、h4~h6 依次递增░░数量形成清晰的视觉层级。代码块Code Blocks代码块的语法高亮由 syntect crate 驱动支持一系列现成高亮主题其中包括完整列表见 docs/src/features/themes/definition.mdbase16-ocean.dark、base16-eighties.dark、base16-mocha.dark、base16-ocean.light、Catppuccin、Coldark、DarkNeon、InspiredGitHub、Nord-sublime、Solarized含 dark/light 变体、TwoDark、dracula-sublime、github-sublime-theme、gruvbox、onehalf、sublime-monokai-extended、sublime-snazzy、visual-studio-dark-plus、zenburn。其中大部分来自 bat 工具项目高亮主题资源本身也随仓库的 bat 目录以二进制形式打包提供。代码块可配置的属性code: # The code theme. theme_name: base16-eighties.dark # The padding to be applied, in cells, around a code snippet. padding: horizontal: 2 vertical: 1 # Whether the themes background color should be used around the code block. background: false # Whether to set line numbers in all snippets by default. line_numbers: false自定义高亮主题除了内置高亮主题你还可以把任意.tmTheme文件放入配置目录的themes/highlighting子目录Linux 上即~/.config/presenterm/themes/highlighting/presenterm 启动时会自动加载它们。加载入口在 src/main.rs 的load_themesHighlightThemeSet::register_from_directory(themes_path.join(highlighting))。引用块Block Quotes引用块的每一行文本都可以带一个前缀字符串block_quote: prefix: ▍ Mermaid 图表Mermaid 图表支持两个定制参数mermaid.background传给 CLI 的背景色如transparent、red、#F0F0F0mermaid.theme使用的 Mermaid 主题。mermaid: background: transparent theme: dark警报AlertsGitHub 风格的 Markdown 警报alert可以通过alert键定制包括整体底色、每行前缀以及每种警报类型各自的颜色、标题与图标alert: # the base colors used in all text in an alert base_colors: foreground: red background: black # the prefix used in every line in the alert prefix: ▍ # the style for each alert type 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对应的AlertStyle/AlertTypeStyle数据结构含color、title、icon三个字段见 src/theme/raw.rs。主题继承extends自定义主题可以继承另一个自定义主题或内置主题默认继承其全部属性只覆写差异部分。这在内置主题大体满意、只想改几个属性的场景下非常有用extends: dark default: colors: background: 000000这个主题继承内置dark主题并把背景色改为纯黑。继承在加载时通过merge_struct::merge完成字段级合并且支持多级链式继承同时注册器会对继承关系做完备性检查继承目标不存在、出现循环继承都会在加载时报错见上文注册与校验的源码细节。另外注意front matter 的theme.override中不允许使用extends而自定义主题文件中则允许。调色板Color Palette每个主题都可以定义自己的调色板包含两类内容colors预定义颜色列表classes一组前景色/背景色对即样式类。palette: colors: red: f78ca2 purple: 986ee2 classes: foo: foreground: ff0000 background: 00ff00调色板中的颜色可用palette:name或简写p:name引用主题中任何需要颜色的位置都可以使用例如p:red、p:purple。在 themes/dark.yaml 中可以看到这种用法的全貌——整套主题几乎全部通过palette:引用集中定义的颜色palette:blue、palette:orange、palette:light_green等避免了同一颜色在文件里反复出现。这些颜色与样式类同样可以在演示文稿正文中通过 HTML 标签使用span stylecolor: palette:redthis is red/span span classfoothis is foo-colored/spanspan classfoo会同时应用foo类的前景色与背景色。这类用法不仅限于正文也适用于模板页脚与 intro slide 等场景。调色板在源码中由ColorPalette结构表示colors与classes均为有序映射RawColor::resolve负责把Palette(name)、ForegroundClass(name)、BackgroundClass(name)解析为最终颜色未定义的调色板颜色会抛出UndefinedPaletteColorError。粗体与斜体样式默认情况下粗体与斜体文本不会被赋予任何颜色。如果你想为它们统一着色可以使用顶层bold与italics键italics也接受别名italicbold: colors: foreground: red italics: colors: background: blue实用排查技巧预览主题presenterm --list-themes一次看遍所有内置主题的渲染效果确认生效主题presenterm --current-theme打印当前演示实际使用的主题名快速微调利用 front matter 的theme.override直接在演示文件中改样式保存即热重载非常适合现场调色从现成主题起步仓库 themes 目录下的每个内置主题都是完整的 YAML 样例复制一份放进~/.config/presenterm/themes/再修改是最稳妥的自定义起点严格校验主题 YAML 使用deny_unknown_fields解析写错键名会直接报错继承、重名、循环等异常在加载期即被拦截并给出明确错误信息。至此从选一套内置主题到写一份带调色板与页脚模板的完整自定义主题再到理解 front matter 覆写与主题继承的合并规则你已经掌握了 presenterm 主题体系的全部关键路径。想进一步深入可继续阅读 主题定义详解 与 配置说明并结合 config.sample.yaml 与仓库中的主题文件逐项验证。【免费下载链接】presentermA markdown terminal slideshow tool项目地址: https://gitcode.com/GitHub_Trending/pr/presenterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考