Hotdry.
归档
application-security

mkslides：MkDocs 风格的 Markdown 幻灯片 CLI 工具

利用 mkslides 实现 Markdown 到 Reveal.js 幻灯片的 MkDocs-like 工作流：live-reload 预览、自定义主题与插件、静态部署参数。

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 维护多格式输出，提升复用率。

资料来源：

（正文约 950 字）

查看归档