Hugo 主题
reveal-hugo
- 作者:Josh Dzielak
- GitHub 星星:696
- 更新时间:2024-10-30
- 许可证:MIT
reveal-hugo
一个用于 Reveal.js 的 Hugo 主题,使编写和自定义变得轻而易举。有了它,你可以将任何格式正确的 Hugo 内容转换为 HTML 演示文稿。
⚠️ 此主题的最新版本需要 hugo 版本 >= v0.93.0。如果你需要与早期版本兼容,请尝试之前的版本。
示例
使用 reveal-hugo,只需一个 markdown 文件即可创建包含多个幻灯片的演示文稿,如下所示
+++
title = "How to say hello"
+++
# English
Hello.
---
# Français
Salut.
---
# Español
Hola.
只需使用被空行包围的 ---
将内容分割成不同的幻灯片。
文档
请访问 reveal-hugo.dzello.com 查看使用此主题创建的演示文稿,并了解可供你使用的所有不同功能。
有关 reveal-hugo 的完整博文,请查看 Forestry.io 博客上的《利用静态站点生成器的强大功能来创建演示文稿》。
演示
跳转到此存储库中的 exampleSite 文件夹,以查看上述演示文稿以及更多演示文稿的源代码。以下是这些演示文稿的实时链接
- logo-example - 展示如何向演示文稿添加徽标
- custom-theme-example - 使用 Hugo pipes 编译并使用自定义 Reveal.js SCSS 主题(推荐!)
- section-example - 一个非常基本的示例,展示如何为 Hugo 部分创建演示文稿
- plugin-example - 展示如何向演示文稿添加其他 Reveal.js 插件,例如图片库
- template-example - 使用幻灯片简码和强大模板的示例
- bundle-example - 从叶包中的一个或多个 markdown 文件创建演示文稿的示例
- hugo-hl-example - 使用 Hugo 的编译时语法突出显示的示例
- highlightjs-linenumbers-example - 使用 highlight.js 的多行和多步功能的示例
- 空白的 Reveal-Hugo 模板 - 一个模板化的骨架站点,可快速入门
入门存储库
如果你想立即开始创建演示文稿,请克隆 programming-quotes 存储库并开始修改。
教程:创建你的第一个演示文稿
即使你之前没有 Hugo 或 Reveal.js 的知识,也应该能够完成本节。最后,你将获得一个带有即时重新加载功能的可用演示文稿。
创建一个 Hugo 骨架站点
首先,安装 Hugo 并创建一个新的 Hugo 站点
hugo new site my-presentation
切换到新站点的目录
cd my-presentation
初始化一个 git 存储库
git init
获取 reveal-hugo
主题
方法 1(推荐):将主题用作 hugo 模块
通过从站点根目录发出此命令,将新的骨架站点转换为 hugo 模块
hugo mod init github.com/me/my-presentation
- 将
reveal-hugo
主题模块声明为站点的依赖项
hugo mod get github.com/joshed-io/reveal-hugo
打开 hugo.toml
并添加以下行
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"]
配置你的演示文稿
在你的 hugo.toml
中添加更多内容
[markup.goldmark.renderer]
unsafe = true
[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true
这告诉 Hugo 使用 reveal-hugo 主题,并注册一个名为“Reveal”的新输出格式。
接下来,在 content/_index.md
中创建一个文件并添加以下内容
+++
title = "My presentation"
outputs = ["Reveal"]
+++
# Hello world!
This is my first slide.
回到命令行,运行
$ hugo server
导航到 https://127.0.0.1:1313/,你应该会看到你的演示文稿。
要添加更多幻灯片,只需将内容添加到 _index.md
或在 content/home
中创建新的 markdown 文件。请记住,每个幻灯片必须由 ---
分隔,上下都有空行。
# Hello world!
This is my first slide.
---
# Hello Mars!
This is my second slide.
克隆现有存储库(仅限方法 2)
如果你有一个使用上述步骤设置的现有存储库,则在克隆你的存储库后,必须使用以下命令拉取主题子模块
git submodule update --init
主题更新(仅限方法 1)
当将 reveal-hugo
主题用作 hugo 模块时,更新主题非常容易
在命令提示符下,更改到现有站点的根目录。
cd /path/to/my-presentation
然后使用更新标志 -u
调用 hugo 的模块 get
子命令
hugo mod get -u github.com/joshed-io/reveal-hugo
Hugo 将自动拉取最新的主题版本。就这样,你的更新完成了!
用法
《用法指南》包含在此存储库的 exampleSite 目录中的示例演示文稿中。你可以在 reveal-hugo.dzello.com 上访问实时版本。
根演示文稿与部分演示文稿
以下是包含一个根演示文稿和一个部分演示文稿的文件夹结构。
- content
- home # special section for appending to root presentation
- body.md # appends to the root presentation
- conclusion.md # appends to the root presentation
- _index.md # beginning of the root presentation
- ted-talk
- _index.md # beginning of the ted talk presentation
- body.md # appends to the ted talk presentation
- conclusion.md # appends to the ted talk presentation
这将创建两个演示文稿,一个位于 /
,另一个位于 /ted-talk/
。幻灯片附加到每个演示文稿的顺序可以通过每个文件的前端指定的 weight
参数来控制。_index.md
中的幻灯片将始终排在第一位,但如果你不想,也可以不在此处放置任何幻灯片。
简码
reveal-hugo 附带了各种简码,可帮助你利用 Reveal.js 的一些非常有用的功能。
fragment 简码
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 文档中记录的幻灯片属性列表
autoslide
state
background
background-color
background-image
background-size
background-position
background-repeat
background-opacity
(不透明度为 0-1 刻度,以十进制表示。0=透明,1=不透明。)background-video
background-video-loop
background-video-muted
background-interactive
background-iframe
background-transition
transition
(可以有不同的进入和退出过渡效果)transition-speed
notes
(也可以使用 note 短代码)timing
附加数据属性
请查看 MDN 获取有关这些属性如何工作的信息。
- data-background-image - 要显示的图像的 URL。 GIF 在幻灯片打开时会重新开始播放。
- data-background-size
- data-background-position
- data-background-repeat
- data-background-opacity
你也可以传递自己的属性,每个属性都会自动添加 data-
前缀(id
和 class
除外)。
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 演示文稿。
reveal_hugo.theme
:使用的 Reveal.js 主题;默认为 “black”reveal_hugo.custom_theme
:本地托管的 Reveal.js 主题在 static 或 assets 文件夹中的路径reveal_hugo.custom_theme_compile
:如果设置为 true,则该主题将使用 Hugo pipes 进行编译(并且必须位于 assets 文件夹中)reveal_hugo.custom_theme_options
:提供一个字典来自定义主题编译,请参阅 Hugo 的 SCSS 文档以获取选项列表reveal_hugo.highlight_theme
:使用的 highlight.js 主题;默认为 “default”reveal_hugo.reveal_cdn
:从中加载 Reveal.js 文件的位置;默认为 static 目录中的reveal-js
文件夹以支持离线开发。要改为从 CDN 加载,请将此值设置为https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0
或你喜欢的任何 CDN。reveal_hugo.highlight_cdn
:从中加载 highlight.js 文件的位置;默认为 static 目录中的highlight-js
文件夹以支持离线开发。要改为从 CDN 加载,请将此值设置为https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0
或你喜欢的任何 CDN。reveal_hugo.load_default_plugins
:如果设置为 true (默认值),则会加载默认包含的插件。这些插件是 markdown、highlight.js、notes 和 zoom。reveal_hugo.plugins
:(见下文)要加载的其他 Reveal.js 插件的数组。相应的文件需要已复制到static
或 content 目录中。请参阅此处以获取你可以尝试的大量插件列表。原始实现曾经接受 javascript 文件数组(例如["plugin/gallery/gallery.plugin.js"]
),但现在 reveal-hugo 可以完全加载插件 javascript 和 css。要启用此模式,你需要提供一个插件定义对象数组,其中包含name
、source
和可选的css
、verbatim
和order
字段。Reveal-hugo 将尝试在source
指定的路径加载插件。如果使用verbatim=true
,则按原样尝试该路径。否则,该路径将从 content 目录或static
目录解析。最后,如果未满足其他条件,则将reveal_cdn
添加到路径的前面。order
字段控制 javascript 加载的顺序,很少使用。请参阅 plugin-example 以获取插件演练。
以下参数将如何显示在你的 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.html | reveal-hugo/body.html | reveal-hugo/end.html |
根目录 | home/reveal-hugo/head.html | home/reveal-hugo/body.html | home/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
中设置 relativeURLs
和 uglyURLs
。
relativeURLs = true
uglyURLs = true
注意:uglyURLs
不是严格必需的,但如果你要从文件系统加载,它很有用,因为它确保所有 URL 都以 .html 结尾,并且链接直接指向它们而不是指向文件夹。
教程:向现有 Hugo 站点添加 Reveal.js 演示文稿
如果你的 Hugo 站点已经有一个主题,但你想从它的一些内容创建一个演示文稿,那非常容易。
获取 reveal-hugo
主题
方法 1(推荐):将主题用作 hugo 模块
在你的站点根目录中,检查是否存在文件 go.mod
,该文件将你的站点标记为 hugo 模块。如果此文件尚不存在,请通过从站点根目录发出此命令来创建它
hugo mod init github.com/me/my-presentation
- 将
reveal-hugo
主题模块声明为站点的依赖项
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 功能和快捷方式。
- “s” - 键入“s”进入演讲者模式,这将打开一个单独的窗口,其中包含时间和演讲者备注
- “o” - 键入“o”进入概览模式并滚动浏览幻灯片缩略图
- “f” - 键入“f”进入全屏模式
以下是一些有用的 Reveal.js 相关工具
- decktape 用于将演示文稿导出为 PDF
- 更多 revealjs 主题,包括 robot-lung 和 sunblind
在 Reveal.js wiki 上查找更多信息:插件、工具和硬件。
实现
你是否用 reveal-hugo 构建了一些东西?在此处添加链接。
- dzello 的巴黎婚礼周末指南(源代码)
- DevOps 培训(源代码)
- Pablo Marcos 的个人简历、硕士论文、为世卫组织更新的硕士论文 & 马德里新公交服务提案
更新日志
- 2018-08-03:幻灯片 shortcode 现在更容易使用。自动闭合版本位于幻灯片内部,无需包围其内容并添加闭合标签。
贡献
非常欢迎贡献。请参阅 CONTRIBUTING.md 获取更多详细信息。