Hugo 主题

上一个/下一个: 所有主题

reveal-hugo

reveal-hugo

frag 短代码

类似 fragment 但更简洁 - 内容放置在自闭合的短代码中内联显示。

- {{< frag c="One" >}}
- {{< frag c="Two" >}}
- {{< frag c="Three" >}}

slide 短代码

slide 短代码允许你为每个幻灯片设置自定义 HTML 和 Reveal.js 属性 - 例如 id、class、transition、background 等等。这些名称与 Reveal.js 相同,但没有 “data-” 前缀。

将短代码添加到幻灯片内容上方,--- 分隔符下方。请勿将内容放置在短代码内部。

---

{{< slide id="hello" background="#FFF" transition="zoom" transition-speed="fast" >}}

# Hello, world!

---

这是 Reveal.js 文档中记录的幻灯片属性列表

附加数据属性

请查看 MDN 获取有关这些属性如何工作的信息。

你也可以传递自己的属性,每个属性都会自动添加 data- 前缀(idclass 除外)。

section 短代码

要创建可以垂直导航的幻灯片组,请使用 section 短代码包围你的 markdown。

{{% section %}}

# Vertical slide 1

---

# Vertical slide 2

{{% /section %}}

note 短代码

使用 note 短代码为每个幻灯片添加演讲者备注。

{{% note %}}
Don't forget to thank the audience.
{{% /note %}}

💡 提示:你也可以通过向幻灯片短代码添加 note 属性来添加备注。

markdown 短代码

被 markdown 短代码包围的 Markdown 将不会由 Hugo 渲染,而是由 Reveal.js 本身渲染。如果你想使用 reveal-hugo 不支持的某些原生 Reveal.js markdown 语法,这将非常有用。

{{% markdown %}}
# I'm rendered...
...by Reveal.js
{{% /markdown %}}

数学和公式 (通过 MathJax)

选项 1: math 代码块

你可以在 math 代码块中编写你的公式

```math
\tag*{(1)} P(E) = {n \choose k} p^k (1-p)^{n-k}
```

使用代码块将自动激活所需的 MathJax 脚本以显示公式。

如果你想使用内联公式 (例如 $E=mc^2$),请将你的数学内容包裹在两个单-$中

Albert Einstein's famous formula: $E=mc^2$

如果你想使用内联公式,并且幻灯片中没有用于自动激活的 math 代码块,则需要在页面的 frontmatter 中将参数 math 设置为 true 来手动启用 MathJax

选项 2: math 短代码

或者,你可以在 math 短代码中编写你的公式

{{< math >}}
\tag*{(1)} \frac{n!}{k!(n-k)!} = \binom{n}{k}
{{< /math >}}

使用短代码将自动激活所需的 MathJax 脚本以显示公式。

对于内联公式 (例如 $E=mc^2$),请使用 math 短代码的自闭合形式

Albert Einstein's famous formula: {{< math "E=mc^2" />}}

为了简洁起见,内联内容可以作为未命名的第一个短代码参数给出,如上面的代码片段所示。更简洁的形式中,数学内容也可以分配给名为 inline 的短代码参数:{{< math inline="E=mc^2" />}}

HTML 幻灯片

如果你需要为幻灯片创建比 markdown 更复杂的 HTML,只需将 data-noprocess 添加到 <section> 元素中即可。

<section data-noprocess>
  <h1>Hello, world!</h1>
</section>

可重用的幻灯片和节

有时你需要在同一演示文稿中或跨不同演示文稿重用幻灯片。reveal-hugo 利用 Hugo 数据模板来简化这两种情况。

要创建可重用的幻灯片,请在站点的 data 目录中创建一个 TOML(或 JSON 或 YAML)文件。为其指定一个反映其内容的名称,或者只使用 slides.toml。在该文件中,为每个可重用的幻灯片添加一个键。该名称应反映幻灯片的内容,并且该值应为幻灯片的 markdown。

thankyou = '''

# Thank you!

Any questions?

'''

💡 提示:TOML 的多行字符串语法在这里非常方便,请注意 ‘’’。

每个键可以包含 一个或多个--- 和换行符分隔的幻灯片。这样,你可以创建可重用的节。

thankyou = '''

# Thank you!

---

Any questions?

'''

要从数据模板渲染幻灯片,请使用带有 content 属性的 slide 短代码

{{% slide content="slides.thankyou" /%}}

“.” 之前的部分是数据目录中文件的名称。“.” 之后的部分是要在该文件中查找的键。

你可以使用所有附加的 slide 短代码属性。它们将应用于数据模板中的每个幻灯片。

配置

通过在 hugo.toml 或任何演示文稿的 _index.md 文件的前言中设置这些值来自定义 Reveal.js 演示文稿。

以下参数将如何显示在你的 hugo.toml

[params.reveal_hugo]
theme = "moon"

# the following supposes that menu is accessible in static dir
[[params.reveal_hugo.plugins]]
# Name the plugin. This should be the same name used to register a reveal-js plugin,
# for example: `RevealMenu`, `RevealNotes`
name = "RevealMenu"
source = "menu/menu.js"
css = "menu/menu.css"
# verbatim = true # should the css and source paths be used as-is ?
# order = 6 # control the order in which the plugin should be used.

或者在 _index.md 文件的前言中

[reveal_hugo]
theme = "moon"

[[reveal_hugo.plugins]]
name = "gallery"
source = "plugin/gallery/gallery.plugin.js"
css = "plugin/gallery/gallery.css"

在这些部分中包含你希望作为参数传递给 Reveal.initialize 的任何其他属性,使用 snakecase 格式,例如使用 slide_number 而不是 slideNumber。参数在传递给 Reveal.js 之前会从 snakecase 转换为 camelcase。这是保持参数正确大小写所必需的。

这是一个配置 Reveal.js 参数以及主题和 highlight.js 主题的示例

[reveal_hugo]
theme = "moon"
highlight_theme = "solarized-dark"
slide_number = true
transition = "zoom"

请在此处查看 Reveal.js 配置选项的详细列表。

语法高亮

语法高亮可以使用 Hugo 在编译时完成,也可以使用预装 highlight.js 插件的 Reveal.js 完成。如果演示文稿希望对不同的代码片段使用不同的高亮方式,则可以使用两者。

要使用 Hugo 进行高亮,请使用 highlight 短代码并查看 hugo-hl-example 示例演示文稿。

要查看使用 Reveal.js 进行高亮的示例,请查看 highlightjs-linenumbers-example 演示文稿。

默认情况下,Markdown 代码围栏将由 Hugo 处理。要关闭此功能,请将以下内容添加到你的 hugo.toml 文件中

[markup.highlight]
codeFences = false

现在,围栏中的代码将由 highlight.js 高亮显示。

自定义 Reveal.js 主题

如果你有要使用的自定义 Reveal 主题(以 .css 形式),请将其放置在 static 文件夹中,并在配置中指定它。例如,如果你的 css 文件位于此处

| static
  | stylesheets
    - custom-theme.css

那么这就是你将放入 hugo.toml 中的内容

[params.reveal_hugo]
custom_theme = "stylesheets/custom-theme.css"

使用 Hugo pipes 编译自定义 Reveal.js 主题

Reveal.js 主题定制最简单的方法是通过覆盖 SCSS 或 PostCSS 构建过程中的变量来实现。你可以利用 Hugo pipes 进行主题编译。在这种情况下,你的 SCSS、Saas 或 PostCSS 文件需要位于 assets 文件夹中

| assets
  | stylesheets
    - custom-theme.scss

如果你只想更改演示文稿的颜色,你可以将以下内容放入 custom-theme.scss

@import "../reveal-js/dist/theme/template/mixins";
@import "../reveal-js/dist/theme/template/settings";

$backgroundColor: rgb(3, 129, 45);
$mainColor: #fff;
$headingColor: #fff;

要了解有关 Reveal.js 主题定制的更多信息,请查看 Reveal.js 主题文档。

这是前言的样子

[params.reveal_hugo]
custom_theme = "stylesheets/custom-theme.scss"
custom_theme_compile = true

你还可以添加将传递给 Hugo 的 toCSS 方法的选项

[reveal_hugo.custom_theme_options]
targetPath = "css/custom-theme.css"
enableSourceMap = true

查看 custom-theme-example 演示文稿以查看工作示例。

向布局添加 HTML

如果你需要在 HTML 布局中添加内容,你可以创建位于特定位置的 partials,具体取决于你要自定义哪个演示文稿以及要将 HTML 插入到页面的哪个位置。

演示文稿在 </head> 之前在 </body> 之前div.reveal 的关闭 </div> 之前
所有reveal-hugo/head.htmlreveal-hugo/body.htmlreveal-hugo/end.html
根目录home/reveal-hugo/head.htmlhome/reveal-hugo/body.htmlhome/reveal-hugo/end.html
章节{section}/reveal-hugo/head.html{section}/reveal-hugo/body.html{section}/reveal-hugo/end.html

这是向每个演示文稿添加自定义 CSS 和 JavaScript 的推荐方法。

💡 提示:在 Hugo 中,partials 位于 layouts 文件夹中

例如,如果你有 HTML 要放置在每个演示文稿之前,则结构如下

- layouts
  - partials
    - reveal-hugo
      - head.html
      - body.html
      - end.html

离线开发

默认情况下,离线友好的开发方式是默认的。Reveal.js 和 Highlight.js 文件默认从静态目录加载。(有关如何改为使用 CDN 的信息,请参见上文)。如果需要 file:/// URL 工作,请确保在你的 hugo.toml 中设置 relativeURLsuglyURLs

relativeURLs = true
uglyURLs = true

注意:uglyURLs 不是严格必需的,但如果你要从文件系统加载,它很有用,因为它确保所有 URL 都以 .html 结尾,并且链接直接指向它们而不是指向文件夹。

教程:向现有 Hugo 站点添加 Reveal.js 演示文稿

如果你的 Hugo 站点已经有一个主题,但你想从它的一些内容创建一个演示文稿,那非常容易。

获取 reveal-hugo 主题

在你的站点根目录中,检查是否存在文件 go.mod,该文件将你的站点标记为 hugo 模块。如果此文件尚不存在,请通过从站点根目录发出此命令来创建它

hugo mod init github.com/me/my-presentation
hugo mod get github.com/joshed-io/reveal-hugo

打开 hugo.toml,查找 theme = ... 行,并将 reveal-hugo 添加到你站点的 themes 数组中

theme = ["your-current-theme", "github.com/joshed-io/reveal-hugo"]

方法 2(传统):将主题用作 git 子模块

在 themes 目录中将 reveal-hugo 主题添加为子模块

git submodule add [email protected]:joshed-io/reveal-hugo.git themes/reveal-hugo

打开 hugo.toml,查找 theme = ... 行,并将 reveal-hugo 添加到你站点的 themes 数组中

theme = ["your-current-theme", "reveal-hugo"]

注意:使用低于 0.42 的 Hugo 版本

对于 hugo < v0.42,你必须手动将一些文件从此主题复制到你站点的几个目录中

cd my-hugo-site
git clone https://github.com/joshed-io/reveal-hugo.git themes/reveal-hugo
cd themes/reveal-hugo
cp -r layouts static ../../

文件和目录的命名使得它们不应与你现有的内容冲突。当然,你应该在复制之前仔细检查,特别是不能放在目录下的短代码。

配置站点以进行演示文稿

接下来,将 Reveal 输出格式添加到你站点的 hugo.toml 文件中

[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true

现在,你可以将 outputs = ["Reveal"] 添加到任何章节的 _index.md 文件的前言中,该章节的内容将合并到一个演示文稿中并写入 index.html。如果该章节已经有一个 index.html 页面,只需将上面的 baseName 更改为 reveal,演示文稿将改为放置在 reveal.html 文件中。

注意:如果为单个内容文件指定 outputs = ["Reveal"],则可以阻止为该文件生成任何内容。如果你的其他默认布局会从中创建常规 HTML 文件,则这很有用。演示文稿只需要列表文件。

食谱

从叶子包或单页类型创建演示文稿

默认情况下,reveal-hugo 不会为单页(即 _index.md 之外的页面)创建演示文稿,因为它假设这些页面是 _index.md 开头的章节中较大演示文稿的一部分。如果你的内容结构在叶子包中(主文件是 index.md,没有下划线,Hugo 将其视为单页),或者你只是想将演示文稿放在单个文件中(例如 presentation.md),则可能不是这种情况。在这些情况下,你只需要告诉 Hugo 使用不同的布局。

如果你正在使用叶子页包,请在 index.md 文件的前言中设置以下内容

layout = "bundle"

如果你在像 presentation.md 这样的单页文件中,请在前言中设置以下内容

layout = "list"

创建一个列出所有演示文稿的页面

有关你可以使用的模板,请参阅此问题。

Reveal.js 提示

这些是一些有用的 Reveal.js 功能和快捷方式。

以下是一些有用的 Reveal.js 相关工具

在 Reveal.js wiki 上查找更多信息:插件、工具和硬件。

实现

你是否用 reveal-hugo 构建了一些东西?在此处添加链接。

更新日志

贡献

非常欢迎贡献。请参阅 CONTRIBUTING.md 获取更多详细信息。