presenterm 配置文件完全指南：位置查找、加载流程与 JSON Schema 自动补全

presenterm 配置文件完全指南位置查找、加载流程与 JSON Schema 自动补全【免费下载链接】presentermA markdown terminal slideshow tool项目地址: https://gitcode.com/GitHub_Trending/pr/presentermpresenterm 是一款基于 Markdown 的终端幻灯片工具它通过一份 YAML 配置文件集中管理主题、键位绑定、代码片段执行、公式渲染与导出行为等全部个性化设置。本文以 presenterm 官方配置文档docs/src/configuration/introduction.md为主线结合仓库源码src/config.rs、src/main.rs与示例配置config.sample.yaml完整讲解配置文件的存放位置、自动查找规则、手动指定方式以及如何借助 JSON Schema 让编辑器提供自动补全与校验。配置文件存放位置与查找规则presenterm通过一份config.yaml文件定制行为。该文件与所有自定义主题一起存放在以下平台对应的配置目录中平台配置目录任意平台定义XDG_CONFIG_HOME时$XDG_CONFIG_HOME/presenterm/Linux~/.config/presenterm/macOS~/Library/Application Support/presenterm/Windows~/AppData/Roaming/presenterm/config/运行时presenterm会在上述目录下自动查找名为config.yaml的文件。例如在 Linux 上你应创建~/.config/presenterm/config.yaml。这一查找逻辑在源码中有着明确的实现。查看 src/main.rs 中Customizations::load的代码可以看到当XDG_CONFIG_HOME环境变量存在时配置目录取$XDG_CONFIG_HOME/presenterm否则通过ProjectDirs::from(, , presenterm)得到平台默认配置目录即上表 Linux/macOS/Windows 的路径。随后依次加载themes子目录下的自定义主题与config.yaml配置文件let configs_path: PathBuf match env::var(XDG_CONFIG_HOME) { Ok(path) Path::new(path).join(presenterm), Err(_) { let Some(project_dirs) ProjectDirs::from(, , presenterm) else { return Ok(Default::default()); }; project_dirs.config_dir().into() } }; let themes_path configs_path.join(themes); // ... let config_file_path config_file_path.unwrap_or_else(|| configs_path.join(config.yaml)); let config match Config::load(config_file_path) { Ok(config) config, Err(ConfigLoadError::NotFound) if !require_config_file Default::default(), Err(e) return Err(e.into()), };这里还有一个值得注意的行为如果配置文件不存在且用户没有显式指定配置文件路径presenterm不会报错而是静默回退到全部默认配置Default::default()反之如果你通过--config-file显式指定了路径而文件缺失则会返回ConfigLoadError::NotFound错误参见 src/config.rs 中Config::load的实现。指定自定义配置文件路径除了默认查找你可以通过两种方式覆盖配置文件的路径命令行参数--config-file PATH环境变量PRESENTERM_CONFIG_FILE。在 src/main.rs 中该参数通过 clap 声明并直接绑定环境变量/// The path to the configuration file. #[clap(short, long, env PRESENTERM_CONFIG_FILE)] config_file: OptionString,也就是说以下两种写法的效果等价# 通过命令行参数 presenterm --config-file /path/to/my-config.yaml slides.md # 通过环境变量 PRESENTERM_CONFIG_FILE/path/to/my-config.yaml presenterm slides.md示例配置文件一份可用的起点仓库根目录提供了开箱即用的示例配置文件 config.sample.yaml你可以直接复制到配置目录作为基础再按需增删。其完整内容涵盖了presenterm的主要配置区块--- # yaml-language-server: $schemahttps://raw.githubusercontent.com/mfontanini/presenterm/master/config-file-schema.json defaults: # override the terminal font size when in windows or when using sixel. terminal_font_size: 16 # the theme to use by default in every presentation unless overridden. theme: dark # the image protocol to use. image_protocol: kitty-local typst: # the pixels per inch when rendering latex/typst formulas. ppi: 300 mermaid: # the scale parameter passed to the mermaid CLI (mmdc). scale: 2 options: # whether slides are automatically terminated when a slide title is found. implicit_slide_ends: false # the prefix to use for commands. command_prefix: # show all lists incrementally, by implicitly adding pauses in between elements. incremental_lists: false # this option tells presenterm you dont care about extra parameters in # presentations front matter. This can be useful if youre trying to load a # presentation made for another tool strict_front_matter_parsing: true # whether to treat a thematic break as a slide end. end_slide_shorthand: false snippet: exec: # enable code snippet execution. Use at your own risk! enable: true exec_replace: # enable code snippet automatic execution replacing the snippet with its output. Use at your own risk! enable: true render: # the number of threads to use when rendering render code snippets. threads: 2 speaker_notes: # The endpoint to listen for speaker note events. listen_address: 127.0.0.1:59418 # The endpoint to publish speaker note events. publish_address: 127.0.0.1:59418 # Whether to always publish speaker notes even when --publish-speaker-notes is not set. always_publish: false bindings: # the keys that cause the presentation to move forwards. next: [l, j, right, page_down, down, ] # the keys that cause the presentation to move forwards fast. next_fast: [n] # the keys that cause the presentation to move backwards. previous: [h, k, left, page_up, up] # the keys that cause the presentation to move backwards fast previous_fast: [p] # the key binding to jump to the first slide. first_slide: [gg] # the key binding to jump to the last slide. last_slide: [G] # the key binding to jump to a specific slide. go_to_slide: [numberG] # the key binding to execute a piece of shell code. execute_code: [c-e] # the key binding to reload the presentation. reload: [c-r] # the key binding to toggle the slide index modal. toggle_slide_index: [c-p] # the key binding to toggle the key bindings modal. toggle_bindings: [?] # the key binding to close the currently open modal. close_modal: [esc] # the key binding to close the application. exit: [c-c, q] # the key binding to suspend the application. suspend: [c-z] # the key binding to skip all pauses in the current slide. skip_pauses: [s]注意示例中snippet.exec.enable与snippet.exec_replace.enable被设为true但官方文档明确提醒这属于风险自负use at your own risk的选项默认情况下代码片段执行是禁用的具体讨论见下文配置区块详解。配置文件顶层结构从源码 src/config.rs 中的Config结构体可以看出一份合法的配置文件包含以下 10 个顶层区块均带#[serde(default)]即全部可省略顶层键用途defaults全局默认值默认主题、终端字体大小、图片协议、最大宽高、溢出校验等typstLaTeX/typst 公式渲染的 PPI 像素密度mermaidmermaid CLI 路径、缩放比例、puppeteer 与 mermaid 配置文件d2d2 图的缩放比例options可被演示文稿 front matter 覆盖的行为选项详见下文bindings全部键盘键位绑定snippet代码片段执行、替换执行、渲染线程数与自定义执行器speaker_notes演讲者备注的监听/发布地址exportPDF/HTML 导出的尺寸、分页策略与字体transition幻灯片切换动画的时长、帧数与风格该结构体同时标有#[serde(deny_unknown_fields)]这意味着任何不在上表内的顶层键都会导致解析失败从而第一时间发现配置拼写错误而不是被静默忽略。实际加载流程见 src/config.rsConfig::load读取文件内容后交给serde_yaml::from_str反序列化任何 YAML 语法或字段错误都会包装为ConfigLoadError::Invalid抛出。编辑器自动补全接入 JSON Schemapresenterm提供了一份描述配置文件结构的 JSON Schema位于仓库根目录 config-file-schema.json。这份 schema 可以直接与 yaml-language-server 等 YAML 语言服务配合使用——VS Code 的 YAML 扩展、Neovim 的 yaml-language-server 等工具都基于它工作。只需在配置文件的第一行加入如下注释编辑器便会自动拉取 schema并提供键位补全、枚举值提示与字段文档# yaml-language-server: $schemahttps://raw.githubusercontent.com/mfontanini/presenterm/master/config-file-schema.json从源码看这份 schema 并非手工维护而是由代码自动生成Config结构体上标注了#[cfg_attr(feature json-schema, derive(schemars::JsonSchema))]src/config.rs运行带有json-schemafeature 的程序并传入--generate-config-file-schema参数即可把 schema 输出到标准输出src/main.rscargo run --features json-schema -q -- --generate-config-file-schema config-file-schema.json仓库还配套了两个维护脚本scripts/generate-config-file-schema.sh在 Docker 容器中以固定 Rust 版本重新生成 schema 并覆盖仓库内的 config-file-schema.jsonscripts/validate-config-file-schema.sh重新生成 schema 并与仓库内版本比对若不一致则 CI 报错确保 schema 始终与代码同步。也就是说只要配置结构体变化schema 与编辑器提示就会随之更新二者不会漂移。配置区块详解上文introduction.md定义了配置文件在哪里、如何被加载、如何获得自动补全而options与settings两大区块的具体参数官方文档分别在 docs/src/configuration/options.md 与 docs/src/configuration/settings.md 中有详尽说明。为了让本文具备完整的实战价值这里做概要梳理详细示例请直接阅读上述两篇文档options 区块可在配置文件或演示文稿 front matter 中设置选项作用implicit_slide_ends遇到幻灯片标题即隐式结束上一张幻灯片省去!-- end_slide --end_slide_shorthand将主题分隔线---thematic break视为幻灯片结束符h1_slide_titles是否将幻灯片内第一个h1标题自动作为幻灯片标题command_prefix为 HTML 注释命令设置前缀避免普通单行注释被误判为命令incremental_lists为所有列表项自动插入暂停实现逐项展示incremental_tables为所有表格行自动插入暂停strict_front_matter_parsing是否严格解析 front matter设为false可加载为其他工具编写的演示文稿image_attributes_prefix图片尺寸属性前缀默认image:可改为空字符串以支持width:50%auto_render_languages这些语言的代码块自动视为带render例如mermaidlist_item_newlines列表项之间的换行数默认1defaults 区块只能在配置文件中设置theme默认主题。既可以是字符串如light也可以是{dark: ..., light: ...}结构让presenterm依据终端前景/背景色自动切换terminal_font_size终端字体大小默认 16主要用于 Windows 或图片显示尺寸异常的场景image_protocol图片协议可选auto默认自动探测、kitty-local、kitty-remote、iterm2、sixel、ascii-blocks各协议含义与取值可在 src/config.rs 的ImageProtocol枚举中查看max_columns/max_columns_alignment与max_rows/max_rows_alignment限制演示文稿的最大宽度/高度及对齐方式居中/左/右/顶部/底部incremental_lists配置增量列表在列表前后是否暂停pause_before/pause_after默认均为truevalidate_overflows溢出校验策略取值为never默认、always、when_presenting、when_developing。snippet 区块exec.enable启用代码片段执行exec。出于安全考虑默认禁用可临时用-x参数开启或在此全局开启exec_replace.enable启用执行并用输出替换代码片段exec_replace同样默认禁用、风险自负可用-X参数临时开启render.threadsrender片段异步渲染的线程数默认 2exec.custom为不支持的语言自定义执行器可指定filename、environment、hidden_line_prefix与一组commands也可覆盖内置执行器内置执行器清单见 executors.yaml。speaker_notes / mermaid / d2 / typst 区块speaker_noteslisten_address、publish_address默认127.0.0.1:59418与always_publish免去每次传--publish-speaker-notesmermaidcli默认mmdc/mmdc.cmd、scale默认 2、config_filemermaid 配置文件、puppeteer_config_filed2.scaled2 CLI 的缩放参数typst.ppiLaTeX/typst 公式渲染的每英寸像素数默认 300。transition 与 export 区块transitionduration_millis默认 1000、frames默认 30与animation.styleslide_horizontal、fade、collapse_horizontal支持枚举见 src/config.rsexportdimensions导出页面的columns/rows、pausesignore或new_slide、snippetsparallel或sequential与pdf.fontsPDF 导出的 normal/bold/italic/bold_italic 四种字形字体路径。从配置文件到运行时生效完整调用链综合以上源码一条配置从磁盘到生效的完整链路是main解析 CLI读取--config-file绑定PRESENTERM_CONFIG_FILE环境变量得到config_file: OptionStringCustomizations::load计算配置目录优先$XDG_CONFIG_HOME/presenterm否则使用平台默认配置目录若未显式指定路径则拼接config.yamlsrc/main.rsConfig::load读取文件内容并交由serde_yaml反序列化为强类型Configsrc/config.rs后续各模块从config中提取所需片段如ThirdPartyConfigs取出 typst/mermaid/d2/线程数配置src/main.rsSnippetExecutor::new消费自定义执行器src/main.rsconfig.bindings.try_into()构建键盘命令映射src/main.rs。值得一提的是src/config.rs 中内置的单元测试如default_bindings与default_options_serde验证了默认键位配置可被成功解析、options区块可被 YAML 反序列化从侧面印证了配置解析的健壮性。总结与最佳实践配置文件位置优先$XDG_CONFIG_HOME/presenterm/config.yaml否则依平台使用~/.config/presenterm/Linux、~/Library/Application Support/presenterm/macOS、~/AppData/Roaming/presenterm/config/Windows覆盖路径--config-file参数或PRESENTERM_CONFIG_FILE环境变量二者等价从零开始直接复制 config.sample.yaml 到配置目录按需增删编辑体验在配置首行加入# yaml-language-server: $schema...引用 config-file-schema.json即可获得自动补全与字段说明区分两种设置options区块既可写进配置文件、也可写进单个演示文稿的 front matter适合随文稿分发其余所有区块只能通过配置文件设置注意安全开关snippet.exec与snippet.exec_replace默认禁用仅在信任演示文稿来源时全局开启保持 schema 同步若修改配置结构使用cargo run --features json-schema -- --generate-config-file-schema重新生成 schema并参考 scripts/validate-config-file-schema.sh 验证一致性。【免费下载链接】presentermA markdown terminal slideshow tool项目地址: https://gitcode.com/GitHub_Trending/pr/presenterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考