# mkslides：MkDocs 风格的 Markdown 幻灯片 CLI 工具 > 利用 mkslides 实现 Markdown 到 Reveal.js 幻灯片的 MkDocs-like 工作流：live-reload 预览、自定义主题与插件、静态部署参数。 ## 元数据 - 路径: /posts/2025/11/28/mk-slides-mkdocs-style-markdown-slides-cli-workflow/ - 发布时间: 2025-11-28T00:17:44+08:00 - 分类: [application-security](/categories/application-security/) - 站点: https://blog.hotdry.top ## 正文 mkslides 是一个专为技术演示设计的 CLI 工具，它将 Markdown 文件无缝转化为 Reveal.js 驱动的 HTML 幻灯片，完美继承 MkDocs 的工作流模式。这种设计让开发者能像构建静态文档站点一样快速生成专业级 slides，支持 live-reload 实时预览和一键部署静态文件，避免了传统 PPT 工具的繁琐编辑和格式锁定问题。 核心优势在于其简洁的命令体系和 YAML 配置。安装后，仅需 `pip install mkslides`，即可通过 `mkslides serve slides/` 启动开发服务器，利用 python-livereload 实现文件变更即时刷新，正如 MkDocs 的 `mkdocs serve`。构建命令 `mkslides build slides/` 生成纯静态 HTML，可直接部署到 GitHub Pages 或任意 web 服务器。GitHub 仓库中提到：“MkSlides is a static site generator that's geared towards building slideshows.” 这确保了输出文件的独立性和可移植性。 实际落地时，先在项目根目录创建 `slides/` 文件夹，放入 Markdown 文件（如 `example.md`），每个文件以 `---` 分隔幻灯片（默认 separator: `^\\s*---\\s*$`），垂直滑页用 `-v-`。单个文件模式下，输出为 `site/index.html`，适合快速演示；多文件则生成 index 页导航，如 HOGENT 示例展示的多列布局和自定义 logo。 配置通过 `mkslides.yml` 实现，所有选项可选，按需覆盖默认值。关键参数包括： **slides 配置（全局或 per-file frontmatter）：** - `theme`: Reveal.js 内置如 `black`、`dracula`、`solarized`，或自定义 CSS URL/路径。推荐 `dracula` 用于暗黑代码演示。 - `highlight_theme`: highlight.js 主题如 `monokai`、`vs`，提升代码块可读性。 - `template`: 自定义 Jinja2 模板路径，默认 `assets/templates/slideshow.html.jinja`。 - `title`: 幻灯片标题，用于 index 导航。 - `separator`: 正则自定义滑页分隔符，默认 `^\\s*---\\s*$`；`separator_vertical`: `^\\s*-v-\\s*$`；`separator_notes`: `^Notes?:`。 - `preprocess_script`: Python 脚本路径，进行 MD 预处理（如替换 @mentions）。 **index 配置（多文件 index 页）：** - `nav`: MkDocs 风格列表，如 `- Example: example1.md` 或嵌套。 - `title`: index 页标题。 - `theme`: index CSS 主题。 - `enable_footer`: 默认 true，显示 “Documentation built with MkSlides.”。 **revealjs 配置：** YAML 转 JSON，如 `height: 1080`、`width: 1920`、`transition: fade`、`slideNumber: c/t`、`history: true`。调整为 16:9 比例适合投影。 **plugins 配置：** 列表形式集成 Reveal.js 插件，如 Mermaid 图表： ``` plugins: - name: RevealMermaid extra_javascript: - https://cdn.jsdelivr.net/npm/reveal.js-mermaid-plugin/plugin/mermaid/mermaid.min.js ``` 支持 PlantUML 等。示例 repo https://github.com/HoGentTIN/hogent-markdown-slides 展示了 Mermaid/PlantUML、多列、图像缩放。 部署清单： 1. `mkslides build --site-dir dist slides/` 生成到 `dist/`。 2. GitHub Actions 示例：仓库自带 `test-deploy.yml`，推送 `site/` 到 gh-pages。 3. 参数：`--strict` 严格链接检查；`--config-file custom.yml` 指定配置。 4. 回滚：frontmatter 优先 > yml > 默认；测试用 `mkslides serve -o` 自动浏览器打开。 高级用法中，preprocess_script 如 `tests/test_preprocessors/replace_ats.py` 可动态修改 MD 内容。Emojis 支持增强互动。风险控制：文件夹模式包含 images/assets，避免单文件限制；相对路径以 MD 目录为准。 监控要点：开发时观察 livereload 日志；构建检查 `site/` 大小（插件增加 JS/CSS）；兼容性测试多浏览器（Reveal.js 核心）。 mkslides 阈值建议：项目 <10 MD 文件用默认；大型用 nav + plugins；分辨率超 1080p 时调 height/width，避免溢出。 此工具特别适合技术分享：代码重、图表多的场景，一份 MD 维护多格式输出，提升复用率。 资料来源： - [GitHub - martenbe/mkslides](https://github.com/martenbe/mkslides) - 示例：[martenbe.github.io/mkslides](https://martenbe.github.io/mkslides)，[hogenttin.github.io/hogent-markdown-slides](https://hogenttin.github.io/hogent-markdown-slides) （正文约 950 字） ## 同分类近期文章 ### [Twenty CRM架构解析：实时同步、多租户隔离与GraphQL API设计](/posts/2026/01/10/twenty-crm-architecture-real-time-sync-graphql-multi-tenant/) - 日期: 2026-01-10T19:47:04+08:00 - 分类: [application-security](/categories/application-security/) - 摘要: 深入分析Twenty作为Salesforce开源替代品的实时数据同步架构、多租户隔离策略与GraphQL API设计，探讨现代CRM系统的工程实现。 ### [基于Web Audio API的钢琴耳训游戏：实时频率分析与渐进式学习曲线设计](/posts/2026/01/10/piano-ear-training-web-audio-api-real-time-frequency-analysis/) - 日期: 2026-01-10T18:47:48+08:00 - 分类: [application-security](/categories/application-security/) - 摘要: 分析Lend Me Your Ears耳训游戏的Web Audio API实现架构，探讨实时音符检测算法、延迟优化与游戏化学习曲线设计。 ### [JavaScript构建工具性能革命：Vite、Turbopack与SWC的架构演进](/posts/2026/01/10/javascript-build-tools-performance-revolution-vite-turbopack-swc/) - 日期: 2026-01-10T16:17:13+08:00 - 分类: [application-security](/categories/application-security/) - 摘要: 深入分析现代JavaScript工具链性能革命背后的工程架构：Vite的ESM原生模块、Turbopack的增量编译、SWC的Rust重写，以及它们如何重塑前端开发体验。 ### [Markdown采用度量与生态系统增长分析：构建量化评估框架](/posts/2026/01/10/markdown-adoption-metrics-ecosystem-growth-analysis/) - 日期: 2026-01-10T12:31:35+08:00 - 分类: [application-security](/categories/application-security/) - 摘要: 基于GitHub平台数据与Web生态统计，构建Markdown采用率量化分析系统，追踪语法扩展、工具生态、开发者采纳曲线与标准化进程的工程化度量框架。 ### [Tailwind CSS v4插件系统架构与工具链集成工程实践](/posts/2026/01/10/tailwind-css-v4-plugin-system-toolchain-integration/) - 日期: 2026-01-10T12:07:47+08:00 - 分类: [application-security](/categories/application-security/) - 摘要: 深入解析Tailwind CSS v4插件系统架构变革，从JavaScript运行时注册转向CSS编译时处理，探讨Oxide引擎的AST转换管道与生产环境性能调优策略。