Skip to content

幻灯片生成指南

本文档介绍如何使用 Marp 生成和管理多语言幻灯片的新工作流。

快速开始

文件与资源组织

  • 所有 .md 幻灯片文件及依赖的图片、样式等静态资源统一放在 static/slides 目录下。
  • 建议每个演示文稿单独建子目录，如：
static/slides/my-presentation/slides.md
static/slides/my-presentation/background.jpg
static/slides/another-talk/slides.md

生成幻灯片 HTML

请使用 Marp CLI 手动编译：

marp static/slides/my-presentation/slides.md -o static/slides/my-presentation/slides.html

如需批量生成，可自行编写 shell 脚本遍历 static/slides 目录。

不再提供 Makefile 命令，所有生成操作需手动完成。

功能特性

1. 统一目录管理

  • 所有幻灯片及资源集中在 static/slides 下，便于查找和维护
  • 支持多语言内容，建议以子目录区分

2. 多语言支持

  • 可在 static/slides/zh/、static/slides/en/ 等子目录下分别存放不同语言的幻灯片
  • 目录结构自定义灵活

3. 路径与输出

  • 源文件与输出文件均在 static/slides 下，推荐 slides.md → slides.html 命名

4. 生成与优化

  • 使用 @marp-team/marp-cli 手动编译 .md 文件为 HTML
  • 可在 .md 文件中自定义主题、样式和资源
  • 生成的 HTML 文件直接可被 Hugo 访问和嵌入

5. 错误处理

  • 编译前请确认文件路径和格式正确
  • Marp CLI 未安装可通过 npm install -g @marp-team/marp-cli 安装
  • 资源引用请使用相对路径，确保在 static/slides 下可访问

移动端优化

建议在 .md 文件中使用官方或自定义主题，支持响应式布局和移动端体验。

CSS 优化

  • 响应式控制栏布局
  • 触摸友好的按钮尺寸
  • 横屏模式适配
  • 高 DPI 屏幕支持

iOS 特殊处理

  • 全屏按钮强制显示
  • iOS 设备检测（包括新 iPad Pro）
  • 多重全屏 API 尝试
  • 自定义全屏模拟（当原生 API 不可用时）

开发工作流

1. 创建幻灯片

# 创建新的幻灯片目录
mkdir -p static/slides/my-presentation
# 创建 .md 文件
touch static/slides/my-presentation/slides.md

2. 编辑内容

在 .md 文件中编写 Markdown 内容，使用 Marp 语法。

3. 生成 HTML

marp static/slides/my-presentation/slides.md -o static/slides/my-presentation/slides.html

4. 预览效果

# 启动 Hugo 开发服务器
make server
# 访问 http://localhost:1313/slides/my-presentation/slides.html

其他说明

  • 可根据需要在 static/slides 下自定义目录结构和命名
  • 推荐将所有相关资源（图片、样式等）与 .md 文件放在同一目录

与服务器解耦

幻灯片生成与 Hugo 服务器完全解耦：

  • Hugo 仅负责静态资源服务
  • 幻灯片需手动生成 HTML 文件后方可访问

依赖检查

请确保已安装以下工具：

  • Node.js
  • @marp-team/marp-cli
  • Hugo

故障排除

常见问题

  1. Marp CLI 未安装
npm install -g @marp-team/marp-cli

  1. 路径问题 请确保在项目根目录或 static/slides 目录下执行 marp 命令

  2. 资源引用问题 图片等资源请使用相对路径，确保 HTML 能正确访问

最佳实践

  1. 文件组织：将相关资源与 .md 文件放在同一目录下
  2. 命名规范：推荐使用 slides.md 作为主文件名，输出为 slides.html
  3. 定期生成：内容更新后及时重新生成 HTML 文件
  4. 版本控制：将 .md 和生成的 HTML 文件一并纳入版本控制

扩展功能

自定义主题

在 .md 文件中指定主题：

---
marp: true
theme: custom
---

背景图片

使用相对路径引用图片：

![bg](background.jpg)

多语言支持

为不同语言创建对应的目录结构：

static/slides/zh/presentation/slides.md
static/slides/en/presentation/slides.md

文档系统集成

MkDocs 文档服务器

项目还包含完整的 MkDocs 文档系统，用于管理技术文档：

# 启动 MkDocs 文档服务器
make docs

# 构建静态文档
make docs-build

文档访问

  • 本地开发: http://127.0.0.1:8000
  • 文档内容: 包含幻灯片生成指南、移动端优化等技术文档
  • 搜索功能: 支持全文搜索和导航
  • 响应式设计: 移动端友好的文档界面

相关文档