reveal-md

基于 [reveal.js][1] 的增强版!从 Markdown 文件生成漂亮的 reveal.js 演示文稿。

安装

npm install -g reveal-md

使用

reveal-md slides.md

这会启动一个本地服务器,并在默认浏览器中将任何 Markdown 文件作为 reveal.js 演示文稿打开。

Docker

你可以使用 Docker 运行此工具,无需在机器上安装 Node.js。运行公开的 Docker 镜像,将你的 markdown 幻灯片作为卷提供。以下是一些示例:

docker run --rm -p 1948:1948 -v <path-to-your-slides>:/slides webpronl/reveal-md:latest
docker run --rm -p 1948:1948 -v <path-to-your-slides>:/slides webpronl/reveal-md:latest --help

服务现在运行在 [http://localhost:1948][2]。

要在容器中启用实时重载,还应该映射端口 35729:

docker run --rm -p 1948:1948 -p 35729:35729 -v <path-to-your-slides>:/slides webpronl/reveal-md:latest /slides --watch

功能

• [安装][3]
• [使用][4]
• [Docker][6]
• [功能][7]
  • [Markdown][8]
    • [代码部分][59]
  • [主题][9]
  • [高亮主题][10]
  • [自定义幻灯片分隔符][11]
  • [自定义幻灯片属性][12]
  • [reveal-md 选项][13]
  • [Reveal.js 选项][14]
  • [演讲者注释][15]
  • [YAML Front matter][16]
  • [实时重载][17]
  • [自定义脚本][18]
  • [自定义 CSS][19]
  • [自定义 Favicon][20]
  • [预处理 Markdown][21]
  • [打印为 PDF][22]
    • [1. 使用 Puppeteer][23]
    • [2. 使用 Docker 和 DeckTape][24]
  • [静态网站][25]
  • [禁用自动打开浏览器][26]
  • [目录列表][27]
  • [自定义端口][28]
  • [自定义模板][29]
• [脚本、预处理器和插件][30]
• [相关项目与替代方案][31]
• [致谢][32]
• [许可证][33]

Markdown

reveal.js 的 Markdown 功能非常棒,有一种简单(且可配置)的语法来分隔幻灯片。使用三个破折号,前后各有两个空行(\n---\n)。示例:

# 标题

- 要点 1
- 要点 2

---

## 第二张幻灯片

> 最佳引用。

Note: 演讲者注释很棒!

代码部分

语法高亮

```js
console.log('Hello world!');
```

高亮某些行

你可以高亮一行、多行或两者。

```python [1|3-6]
n = 0
while n < 10:
  if n % 2 == 0:
    print(f"{n} is even")
  else:
    print(f"{n} is odd")
  n += 1
```

主题

覆盖主题(默认:black):

reveal-md slides.md --theme solarized

查看[可用主题][34]。

使用自定义主题覆盖 reveal 主题。在此示例中,文件位于 ./theme/my-custom.css:

reveal-md slides.md --theme theme/my-custom.css

使用远程主题覆盖 reveal 主题(使用 rawgit.com,因为 URL 必须允许跨站访问):

reveal-md slides.md --theme https://rawgit.com/puzzle/pitc-revealjs-theme/master/theme/puzzle.css

高亮主题

覆盖高亮主题(默认:zenburn):

reveal-md slides.md --highlight-theme github

查看[可用主题][35]。

自定义幻灯片分隔符

覆盖幻灯片分隔符(默认:\n---\n):

reveal-md slides.md --separator "^\n\n\n"

覆盖垂直/嵌套幻灯片分隔符(默认:\n----\n):

reveal-md slides.md --vertical-separator "^\n\n"

自定义幻灯片属性

使用 [reveal.js 幻灯片属性][36]功能添加 HTML 属性,例如自定义背景。或者,为特定幻灯片添加 HTML id 属性,并使用 CSS 设置其样式。

示例:设置第二张幻灯片使用 PNG 图像作为背景:

# 幻灯片1

这张幻灯片没有背景图像。

---

<!-- .slide: data-background="./image1.png" -->

# 幻灯片2

这张有!

reveal-md 选项

在 Markdown 文件根目录的 reveal-md.json 文件中定义类似于命令行选项的选项。它们会被自动拾取。示例:

{
  "separator": "^\n\n\n",
  "verticalSeparator": "^\n\n"
}

Reveal.js 选项

在项目根目录的 reveal.json 文件中定义 Reveal.js [选项][37]。它们会被自动拾取。示例:

{
  "controls": true,
  "progress": true
}

演讲者注释

使用以 Note: 开头的行来使用[演讲者注释][38]功能。

YAML Front matter

使用 YAML front matter 设置特定演示文稿的 Markdown(和 reveal.js)选项:

---
title: Foobar
separator: <!--s-->
verticalSeparator: <!--v-->
theme: solarized
revealOptions:
  transition: 'fade'
---

Foo

Note: 测试注释

<!--s-->

# Bar

<!--v-->

实时重载

使用 -w 选项,对 markdown 文件的更改将触发浏览器重新加载,从而显示更改后的演示文稿,而无需用户手动重新加载浏览器。

reveal-md slides.md -w

自定义脚本

向页面注入自定义脚本:

reveal-md slides.md --scripts script.js,another-script.js

• 不要使用绝对文件路径,文件应该在相邻或下级文件夹中。
• 允许使用绝对 URL。

自定义 CSS

向页面注入自定义 CSS:

reveal-md slides.md --css style.css,another-style.css

• 不要使用绝对文件路径,文件应该在相邻或下级文件夹中。
• 允许使用绝对 URL。

自定义 Favicon

如果包含 markdown 文件的目录中有 favicon.ico 文件,它将自动用作网站图标,而不是[默认网站图标][39]。

预处理 Markdown

可以通过 --preprocessor (或 -P) 选项为 reveal-md 提供 markdown 预处理器脚本。这对于在不深入研究 Markdown 解析器的情况下实现文档格式的自定义调整很有用。

例如,要让标题自动创建新幻灯片,可以有脚本 preproc.js:

// 标题触发新幻灯片
// 带有插入符号的标题(例如,'##^ foo`)触发新的垂直幻灯片
module.exports = (markdown, options) => {
  return new Promise((resolve, reject) => {
    return resolve(
      markdown
        .split('\n')
        .map((line, index) => {
          if (!/^#/.test(line) || index === 0) return line;
          const is_vertical = /#\^/.test(line);
          return (is_vertical ? '\n----\n\n' : '\n---\n\n') + line.replace('#^', '#');
        })
        .join('\n')
    );
  });
};

并像这样使用它

reveal-md --preprocessor ./preproc.js slides.md

打印为 PDF

至少有两种选项可以将演示文稿导出为 PDF 文件。

1. 使用 Puppeteer

从提供的 Markdown 文件创建(可打印的)PDF:

reveal-md slides.md --print slides.pdf

PDF 是使用 Puppeteer 生成的。或者,在命令行或浏览器中的 URL 后附加 ?view=print(确保删除 #/ 或 #/1 哈希)。然后使用浏览器的(而不是本机的)打印对话框打印幻灯片。这似乎在 Chrome 中可以工作。

默认情况下,纸张大小设置为匹配您的 [reveal.json][14] 文件中的选项,如果没有则回退到默认值 960x700 像素。要覆盖此行为,您可以在命令行选项 --print-size 中传递自定义尺寸或格式:

reveal-md slides.md --print slides.pdf --print-size 1024x768   # 当没有给出单位时以像素为单位
reveal-md slides.md --print slides.pdf --print-size 210x297mm  # 有效单位为: px, in, cm, mm
reveal-md slides.md --print slides.pdf --print-size A4         # 有效格式为: A0-6, Letter, Legal, Tabloid, Ledger

如果出现错误,请尝试以下操作:

• 分析调试输出,例如 DEBUG=reveal-md reveal-md slides.md --print
• 查看 reveal-md help 了解 Puppeteer 参数(puppeteer-launch-args 和 puppeteer-chromium-executable)
• 使用 Docker 和 DeckTape:

2. 使用 Docker 和 DeckTape

当在 Docker 容器中运行 reveal-md 时,第一种打印方法目前不起作用,因此建议您改用 [DeckTape][40] 进行打印。使用 DeckTape 还可能解决内置打印方法输出的问题。

要使用 DeckTape Docker 镜像为在本地主机上运行的 reveal-md 演示文稿创建 PDF,请使用以下命令:

docker run --rm -t --net=host -v $OUTPUT_DIR:/slides astefanutti/decktape $URL $OUTPUT_FILENAME

替换以下变量:

• $OUTPUT_DIR 是你想要保存PDF的文件夹。
• $OUTPUT_FILENAME 是PDF的文件名。
• $URL 是你可以在浏览器中访问演示文稿的地址(不包括?view=print后缀)。如果你没有在Docker中运行reveal-md,你需要将localhost替换为你计算机的IP地址。

要查看完整的导出选项列表,请参阅[DeckTape github][40],或使用-h标志运行Docker容器。

静态网站

这将把提供的Markdown文件导出为一个独立的HTML网站,包括脚本和样式表。文件保存到传递给--static参数的目录(默认为./_static):

reveal-md slides.md --static _site

这应该会连同幻灯片一起复制图片。使用--static-dirs来复制包含其他静态资源的目录到目标目录。使用逗号分隔的列表来复制多个目录。

reveal-md slides.md --static --static-dirs=assets

提供一个目录将生成一个独立的概览页面,其中包含演示文稿的链接(类似于[目录列表][27]):

reveal-md dir/ --static

默认情况下,所有子目录中的所有*.md文件都包含在生成的网站中。使用--glob提供一个自定义的[glob模式][41],仅从匹配的文件生成幻灯片:

reveal-md dir/ --static --glob '**/slides.md'

额外的--absolute-url和--featured-slide参数可以用来生成[OpenGraph][42]元数据,使幻灯片链接在某些社交网站上分享时能够更吸引人地呈现。

reveal-md slides.md --static _site --absolute-url https://example.com --featured-slide 5

禁用自动打开浏览器

要禁用自动打开浏览器:

reveal-md slides.md --disable-auto-open

目录列表

显示Markdown文件的(递归)目录列表:

reveal-md dir/

显示当前目录中Markdown文件的目录列表:

reveal-md

自定义端口

覆盖端口(默认:1948):

reveal-md slides.md --port 8888

自定义模板

覆盖reveal.js HTML模板([默认模板][43]):

reveal-md slides.md --template my-reveal-template.html

覆盖列表HTML模板([默认模板][44]):

reveal-md slides.md --listing-template my-listing-template.html