Skip to content

幻灯片嵌入

概述

slide-embed 是一个用于在网站中嵌入 Marp 生成的幻灯片的功能组件。它支持两种使用方式：

  1. 短代码方式 - 在 Markdown 内容中使用
  2. 模板集成 - 在 slide 布局中自动嵌入

功能特性

  • ✅ 响应式设计，适配不同屏幕尺寸
  • ✅ 可自定义高度和样式
  • ✅ 支持全屏播放
  • ✅ 保持所有 Marp 交互功能
  • ✅ 优雅的错误处理
  • ✅ 现代化的视觉效果（阴影、圆角等）

使用方法

1. 短代码方式

在任何 Markdown 文件中使用：

{{< slide-embed "slides.html" >}}

参数说明

  • src (必需): HTML 文件名，基于根目录的路径，通常为 /slides/<slide-file-folder>/<slide-file-name>.html
  • height (可选): iframe 高度，默认为 100vh
  • style (可选): 额外的 CSS 样式

示例

<!-- 基本用法 -->
{{< slide-embed "slides.html" >}}

<!-- 自定义高度 -->
{{< slide-embed "slides.html" height="70vh" >}}

<!-- 添加自定义样式 -->
{{< slide-embed "slides.html" height="80vh" style="border: 2px solid #007bff;" >}}

2. Slide 布局集成

在 slide 类型的页面中，可以通过 frontmatter 参数控制：

---
title: "我的幻灯片"
layout: single
slide_file: "slides.html"  # 可选，默认为 slides.html
---

# 幻灯片介绍

这里是幻灯片的介绍内容...

## 主要内容

- 要点 1
- 要点 2
- 要点 3

3. 全屏模式

如果 slide 页面没有内容（只有 frontmatter），则会自动以全屏模式显示幻灯片：

---
title: "全屏幻灯片"
layout: single
slide_file: "presentation.html"
---

文件结构

确保您的幻灯片文件与 Markdown 文件在同一目录：

content/
└── slide/
    └── my-presentation/
        ├── index.md          # 页面内容
        ├── slides.html       # Marp 生成的幻灯片
        ├── presentation.html # 其他幻灯片文件
        └── assets/           # 图片等资源
            ├── image1.png
            └── image2.svg

CSS 样式

组件包含以下预定义样式：

容器样式

  • 响应式高度设置
  • 圆角边框 (8px)
  • 阴影效果
  • 黑色背景

响应式断点

  • 桌面: 默认样式
  • 平板 (≤768px): 高度调整为 50vh，圆角减小
  • 手机 (≤480px): 高度调整为 40vh，缩放比例调整

暗色模式支持

  • 自动适配系统暗色模式
  • 调整阴影颜色以适应暗色背景

高级用法

自定义样式

您可以通过 CSS 进一步自定义样式：

.slide-embed-container {
  // 自定义容器样式
  border: 2px solid var(--primary-color);

  &[data-height="custom"] {
    height: 600px;
  }
}

.slide-embed-iframe {
  // 自定义 iframe 样式
  border-radius: 4px;
}

多个幻灯片

在同一页面中嵌入多个幻灯片：

## 第一部分
{{< slide-embed "part1.html" height="60vh" >}}

## 第二部分
{{< slide-embed "part2.html" height="60vh" >}}

## 第三部分
{{< slide-embed "part3.html" height="60vh" >}}

故障排除

常见问题

  1. 幻灯片不显示
  2. 检查文件路径是否正确
  3. 确认 HTML 文件存在于正确位置

  4. 查看浏览器控制台是否有错误信息

  5. 样式显示异常

  6. 确认 SCSS 文件已正确导入
  7. 检查 CSS 缓存是否需要清理

  8. 验证响应式断点设置

  9. 交互功能失效

  10. 确认 Marp 生成的 HTML 包含必要的 JavaScript
  11. 检查是否有 CSP (Content Security Policy) 限制
  12. 验证 iframe 的 allow 属性设置

调试技巧

  1. 使用浏览器开发者工具检查 iframe 内容
  2. 查看网络请求确认文件加载状态
  3. 检查控制台错误信息
  4. 验证文件权限和路径

最佳实践

  1. 文件命名: 使用描述性的文件名，如 introduction.html、main-content.html
  2. 高度设置: 根据内容调整合适的高度，避免过高或过低
  3. 响应式: 测试不同设备上的显示效果
  4. 性能: 对于大型幻灯片，考虑使用懒加载
  5. 可访问性: 确保幻灯片内容具有适当的标题和描述

示例项目

参考现有的幻灯片实现：

  • /content/en/slide/beyond-sidecar/ - 英文版示例
  • /content/zh/slide/beyond-sidecar/ - 中文版示例