抠丁客 抠丁客
项目
编辑 (2024/8/4)

Pandoc 用户使用指南 - 幻灯片展示

你可以使用 pandoc 生成可以在 Web 浏览器中查看的 HTML + JavaScript 幻灯片演示。有五种方法可以实现这一点，使用 S5, DZSlides, Slidy, Slideous, 或者 reveal.js。你也可以使用 LaTeX beamer，或者生成 Microsoft PowerPoint 格式的幻灯片。

以下是简单的幻灯片展示 habits.txt 的 Markdown 源码：

% Habits
% John Doe
% March 22, 2005

# 早晨

## 起床

- 关掉闹钟
- 起床

## 早餐

- 吃鸡蛋
- 喝咖啡

# 晚上

## 晚餐

- 吃意大利面
- 喝葡萄酒

------------------

# Pandoc 用户使用指南 - 幻灯片展示

你可以使用 pandoc 生成可以在 Web 浏览器中查看的 HTML + JavaScript 幻灯片演示。有五种方法可以实现这一点，使用 [S5](https://meyerweb.com/eric/tools/s5/), [DZSlides](https://paulrouget.com/dzslides/), [Slidy](https://www.w3.org/Talks/Tools/Slidy2/), [Slideous](https://goessner.net/articles/slideous/), 或者 [reveal.js](https://revealjs.com/)。你也可以使用 LaTeX [beamer](https://ctan.org/pkg/beamer)，或者生成 Microsoft [PowerPoint](https://en.wikipedia.org/wiki/Microsoft_PowerPoint) 格式的幻灯片。

以下是简单的幻灯片展示 `habits.txt` 的 Markdown 源码：

```text
% Habits
% John Doe
% March 22, 2005

# 早晨

## 起床

- 关掉闹钟
- 起床

## 早餐

- 吃鸡蛋
- 喝咖啡

# 晚上

## 晚餐

- 吃意大利面
- 喝葡萄酒

------------------

![意大利面图片](images/spaghetti.jpg)

## 睡觉

- 上床
- 数羊

要生成 HTML/JavaScript 幻灯片展示，只需键入

pandoc -t FORMAT -s habits.txt -o habits.html

其中 FORMAT 是 s5、slidy、slideous、dzslides 或 revealjs。

对于 Slidy、Slideous、reveal.js 和 S5，使用 -s/--standalone 选项时，pandoc 生成的文件会嵌入指向 JavaScript 和 CSS 文件的链接，这些文件假定位于相对路径 s5/default（对于 S5），slideous（对于 Slideous）、reveal.js（对于 reveal.js），或 Slidy 网站上的 w3.org（对于 Slidy）。 （这些路径可以通过设置 slidy-url、slideous-url、revealjs-url 或 s5-url 变量来更改；参见 HTML 幻灯片变量，以上。）对于 DZSlides，默认情况下会将相对较短的 JavaScript 和 CSS 包含在文件中。

使用所有 HTML 幻灯片格式时，可以使用 --self-contained 选项生成包含显示幻灯片所需的所有数据的单个文件，包括链接的脚本、样式表、图像和视频。

要使用 beamer 生成 PDF 幻灯片，请键入

pandoc -t beamer habits.txt -o habits.pdf

请注意，reveal.js 幻灯片展示也可以通过从浏览器打印到文件转换为 PDF。

要生成 PowerPoint 幻灯片展示，请键入

pandoc habits.txt -o habits.pptx

结构化幻灯片展示

默认情况下，幻灯片级别是文档中直接跟随着内容而非另一个标题的最高等级标题。在上面的例子中，一级标题总是被二级标题跟随，而二级标题后面是内容，因此幻灯片级别是 2。可以使用 --slide-level 选项覆盖此默认值。

根据以下规则将文档划分为幻灯片：

  • 水平分隔线始终开始新的幻灯片。

  • 与幻灯片级别相同的标题始终开始新的幻灯片。

  • 在层级结构中低于幻灯片级别的标题会在幻灯片内部创建标题。（在 beamer 中，会创建一个“区块”。如果标题具有类名 example，则会使用 exampleblock 环境；如果具有类名 alert，则会使用 alertblock；否则会使用常规的 block。）

  • 在层级结构中高于幻灯片级别的标题会创建 “标题幻灯片”，仅包含部分标题，并帮助将幻灯片展示分成多个部分。这些标题下的非幻灯片内容将包含在标题幻灯片中（对于 HTML 幻灯片展示）或在 beamer 中的后续幻灯片中使用相同的标题。

  • 如果存在，则会自动从文档的标题块构造标题页。（在 beamer 的情况下，可以通过注释掉默认模板中的一些行来禁用它。）

这些规则旨在支持多种不同风格的幻灯片展示。如果你不关心将幻灯片划分为部分和子部分，你可以只使用一级标题作为所有幻灯片（在这种情况下，一级将是幻灯片级别）或你可以设置 --slide-level=0。

注意：在 reveal.js 幻灯片展示中，如果幻灯片级别为 2，则将生成二维布局，其中一级标题水平构建，二级标题垂直构建。不建议你在 reveal.js 中使用更深的层级结构，除非你设置了 --slide-level=0（这会让 reveal.js 生成一维布局，并且只将水平分隔线解释为幻灯片边界）。

PowerPoint 布局选择

在创建幻灯片时，pptx 编写器会根据幻灯片的内容从多个预定义布局中进行选择：

  • 标题幻灯片

    如果存在元数据字段中的 [date]、[author] 和 [title]，此布局将用于初始幻灯片，这些幻灯片将从这些字段生成并填充。

  • 章节标题

    此布局用于 pandoc 称之为“标题幻灯片”的幻灯片，即以层级结构中高于幻灯片级别的标题开始的幻灯片。

  • 两栏内容

    此布局用于两栏幻灯片，即包含带有 [columns] 类别的 div 的幻灯片，其中至少包含两个带有 [column] 类别的 div。

  • 比较

    如果至少有一栏包含文本后跟非文本（例如图像或表格），则此布局将代替“两栏内容”用于任何两栏幻灯片。

  • 带图注的内容

    此布局用于任何非两栏幻灯片，这些幻灯片包含文本后跟非文本（例如图像或表格）。

  • 空白

    此布局用于仅包含空白内容的幻灯片，例如仅包含演讲者备注或仅包含不可断开的空间的幻灯片。

  • 标题和内容

    此布局用于所有不符合其他布局标准的幻灯片。

这些布局是从 pandoc 包含的默认 pptx 参考文档中选择的，除非使用 --reference-doc 指定了替代参考文档。

增量列表

默认情况下，这些编写器生成一次性显示的所有列表。如果您希望列表逐项显示，请使用 -i 选项。如果要使特定列表偏离默认设置，请将其放入带有 incremental 或 nonincremental 类别的 div 块中。因此，例如，使用 fenced div 语法，以下无论文档默认设置如何都将增量显示：

::: incremental

- Eat spaghetti
- Drink wine

:::

或者

::: nonincremental

- Eat spaghetti
- Drink wine

:::

虽然使用 incremental 和 nonincremental div 是设置每个案例的增量列表的推荐方法，但也支持一种较旧的方法：将列表放在引号块内将偏离文档默认设置（也就是说，在没有 -i 选项的情况下增量显示，在有 -i 选项的情况下一次性显示）：

> - Eat spaghetti
> - Drink wine

两种方法都允许在单个文档中混合增量和非增量列表。

如果您要在引号块中包含列表，可以通过将列表放在围栏 div 内来规避此行为，以便它不是引号块的直接子元素：

> ::: wrapper
> - a
> - list in a quote
> :::

插入暂停

您可以在幻灯片中通过包含包含三个点的段落来添加 “暂停”，点之间用空格分隔：

# Slide with a pause

content before the pause

. . .

content after the pause

注意：此功能尚未实现在 PowerPoint 输出中。

设置幻灯片样式

可以将自定义 CSS 文件放入 $DATADIR/s5/default（对于 S5），$DATADIR/slidy（对于 Slidy），或 $DATADIR/slideous（对于 Slideous）中以更改 HTML 幻灯片样式，其中 $DATADIR 是用户数据目录（参见 --data-dir，上方）。原始文件可以在 pandoc 的系统数据目录中找到（通常在 $CABALDIR/pandoc-VERSION/s5/default）。如果在用户数据目录中未找到某些文件，pandoc 将在那里查找。

对于 dzslides，CSS 包含在 HTML 文件本身中，并且可以在那里进行修改。

所有 reveal.js 配置选项 都可以通过变量设置。例如，可以通过设置 theme 变量来使用主题：

-V theme=moon

或者可以使用 --css 选项指定自定义样式表。

为了美化 beamer 幻灯片，可以使用 -V 选项指定 theme、colortheme、fonttheme、innertheme 和 outertheme：

pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf

注意，标题属性会转换为 HTML 幻灯片格式中的幻灯片属性（位于 <div> 或 <section> 上），从而允许你单独美化幻灯片。在 beamer 中，一些标题类和属性被识别为帧选项，并将作为选项传递给帧：参见 beamer 中的帧属性，下方。

演讲者备注

在 reveal.js、PowerPoint (pptx) 和 beamer 输出中支持演讲者备注。可以在 Markdown 文档中这样添加备注：

::: notes

This is my note.

- It can contain Markdown
- like this list

:::

要在 reveal.js 中显示备注窗口，请在查看演示文稿时按 s。PowerPoint 中的演讲者备注将像往常一样，在讲义和演讲者视图中可用。

目前其他幻灯片格式不支持备注，但备注不会出现在幻灯片上。

列

要将材料并排放置在列中，可以使用具有类名 columns 的原生 div 容器，其中包含两个或多个具有类名 column 和 width 属性的 div 容器：

:::::::::::::: {.columns}
::: {.column width="40%"}
contents...
:::
::: {.column width="60%"}
contents...
:::
::::::::::::::

注意：目前在 PowerPoint 中指定列宽不起作用。

beamer 中的附加列属性

具有类名 columns 和 column 的 div 容器可选地具有 align 属性。类名 columns 可选地具有 totalwidth 属性或 onlytextwidth 类。

:::::::::::::: {.columns align=center totalwidth=8em}
::: {.column width="40%"}
contents...
:::
::: {.column width="60%" align=bottom}
contents...
:::
::::::::::::::

align 属性可用于 columns 和 column，其值为 top、top-baseline、center 和 bottom 以垂直对齐列。默认情况下 columns 的 align 为 top。

totalwidth 属性限制列的宽度为给定值。

:::::::::::::: {.columns align=top .onlytextwidth}
::: {.column width="40%" align=center}
contents...
:::
::: {.column width="60%"}
contents...
:::
::::::::::::::

类 onlytextwidth 将 totalwidth 设置为 \textwidth。

请参阅 Beamer 用户指南 的第 12.7 节以获取更多详细信息。

在 Beamer 中的幻灯片属性

有时需要向 Beamer 中的幻灯片添加 LaTeX 的 [fragile] 选项（例如，当使用 minted 环境时）。可以通过向介绍幻灯片的标题中添加 fragile 类来强制执行此操作：

# Fragile slide {.fragile}

可以在 Beamer 用户指南 第 8.1 节中描述的所有其他幻灯片属性也可以使用：allowdisplaybreaks, allowframebreaks, b, c, s, t, environment, label, plain, shrink, standout, noframenumbering, squeeze。特别推荐使用 allowframebreaks 属性用于参考文献，因为它允许在内容超出幻灯片的情况下创建多个幻灯片：

# References {.allowframebreaks}

此外，可以使用 frameoptions 属性将任意幻灯片选项传递给 Beamer 幻灯片：

# Heading {frameoptions="squeeze,shrink,customoption=foobar"}

在 reveal.js、Beamer 和 PPTX 中的背景

可以为自包含的 reveal.js 演示文稿、Beamer 演示文稿和 PPTX 演示文稿添加背景图像。

在所有幻灯片上（Beamer、reveal.js、PPTX）

对于 Beamer 和 reveal.js，可以使用配置选项 background-image 在 YAML 元数据块或命令行变量中设置，以便在每张幻灯片上都使用相同的图像。

请注意，对于 reveal.js，background-image 将用作 parallaxBackgroundImage（见下文）。

对于 PPTX，您可以使用设置了相关布局背景图像的 --reference-doc。

parallaxBackgroundImage（reveal.js）

对于 reveal.js，还可以使用原生 reveal.js 选项 parallaxBackgroundImage 来生成视差滚动背景。还必须设置 parallaxBackgroundSize，并可选地设置 parallaxBackgroundHorizontal 和 parallaxBackgroundVertical 来配置滚动行为。有关这些选项含义的更多详细信息，请参阅 reveal.js 文档。

在 reveal.js 的概览模式下，parallaxBackgroundImage 只会在第一张幻灯片上显示。

在个别幻灯片上（reveal.js、PPTX）

要为特定的 reveal.js 或 PPTX 幻灯片设置图像，请向幻灯片上的第一个幻灯片级别标题（甚至可以为空）添加 {background-image="/path/to/image"}。

由于 HTML 编写器会传递未知属性，因此其他 reveal.js 背景设置也可以在个别幻灯片上使用，包括 background-size, background-repeat, background-color, transition, 和 transition-speed。（将自动添加 data- 前缀。）

注意: data-background-image 在 pptx 中也受支持，以便与 reveal.js 保持一致 -- 如果未找到 background-image，将会检查 data-background-image。

在标题幻灯片上 (reveal.js, pptx)

要在为 reveal.js 自动生成的标题幻灯片中添加背景图像，请在 YAML 元数据块中使用 title-slide-attributes 变量。它必须包含属性名称和值的映射。(请注意，这里需要加上 data- 前缀，因为它不会自动添加。)

对于 pptx，请通过设置带有背景图像的“标题幻灯片”布局的 --reference-doc 来实现。

示例 (reveal.js)

---
title: My Slide Show
parallaxBackgroundImage: /path/to/my/background_image.png
title-slide-attributes:
    data-background-image: /path/to/title_image.png
    data-background-size: contain
---

## Slide One

Slide 1 has background_image.png as its background.

## {background-image="/path/to/special_image.jpg"}

Slide 2 has a special image for its background, even though the heading has no content.
在本文档中