HugoHTML启动器

reveal-hugo — Hugo 启动器模板

作者 joshed-io

reveal-hugo 是一个 Hugo 主题,把符合格式的 Hugo 内容转换为基于 Reveal.js 的 HTML 演示文稿,支持用 Markdown 分页、短代码控制幻灯片属性与演讲者备注。

看看你的网站会是什么样

浏览真实页面截图,比较内容排版与手机效果。点击下方缩略图切换,放大查看整页细节。

1 个预览视图
桌面端首页
桌面端截图首屏预览

由服务器浏览器实际访问页面后截取。

目前有 1 张原始预览,可打开完整图片查看设计细节。

截图用于了解视觉与布局,交互效果请以实际项目为准。

采集于 2026-10-02查看来源

值得关注的模板亮点

从已有项目资料中,快速了解它的特点。

01

用 Markdown 编写幻灯片,以空行包围的 `---` 分隔页面

02

提供 fragment、slide、section、note、markdown、math 等短代码控制演示行为

03

支持根演示与 section 演示两种内容组织方式,幻灯片顺序由 weight 控制

04

可通过 Hugo module 或 git submodule 安装,module 方式支持一条命令更新

05

exampleSite 内含 logo、自定义主题、插件、bundle、语法高亮等多个示例源码

模板详细介绍

reveal-hugo 是面向 Hugo 的演示文稿主题,底层使用 Reveal.js 渲染 HTML 幻灯片。它把 Hugo 的内容文件当作幻灯片来源:在 Markdown 中用上下留空行的 `---` 分隔幻灯片,一个文件即可生成多页演示。主题提供多种短代码,包括 fragment/frag(逐条显示)、slide(设置 id、class、transition、background 等 Reveal.js 属性)、section(垂直导航的幻灯片组)、note(演讲者备注)、markdown(交由 Reveal.js 渲染而非 Hugo)以及 math(MathJax 公式)。内容组织上区分根演示与 section 演示:content/_index.md 与 content/home 下的文件组成根演示,其他 section 目录可各自生成独立演示,幻灯片顺序由 front matter 的 weight 控制。主题还附带 exampleSite 目录,包含 logo、自定义主题、插件、模板、bundle、语法高亮等多个示例演示的源码。

使用前需注意:最新版本要求 Hugo >= v0.93.0,旧版 Hugo 需选用较早的 release;需要在配置中注册名为 Reveal 的输出格式,并开启 Goldmark 的 unsafe 渲染。主题可通过 Hugo module 或 git submodule 两种方式安装,前者可用 `hugo mod get -u` 更新。仓库以 MIT 许可发布,但演示图片、字体、图标等第三方素材需单独核对许可;域名、托管等外部服务可能产生费用。

HugoHTML启动器

适合你的项目吗?

适用场景

  • 用 Hugo 站点生成技术分享或教学用的 HTML 演示文稿
  • 把已有的 Markdown 内容快速整理为可分页浏览的幻灯片
  • 在演示中需要逐条显示列表、垂直分节、演讲者备注或 MathJax 公式
  • 参考 exampleSite 中的示例,为演示添加 logo、自定义 SCSS 主题或 Reveal.js 插件

适合人群

  • 已使用 Hugo 并希望以 Markdown 维护演示内容的开发者
  • 需要把演示文稿与站点内容放在同一仓库、同一构建流程中的团队
  • 愿意按文档配置输出格式与短代码、接受 Hugo 版本要求的使用者

上手与定制指南

结合仓库当前版本的说明,按下面的资料检查内容、配置与运行要求。

  1. 1

    最新版本要求 Hugo >= v0.93.0,旧版 Hugo 需改用较早的 release

  2. 2

    安装方式二选一:Hugo module(hugo mod init 后 hugo mod get)或 git submodule 加入 themes 目录

  3. 3

    在 hugo.toml 中设置 theme,并注册 outputFormats.Reveal(baseName = "index")

  4. 4

    开启 markup.goldmark.renderer.unsafe = true,否则部分内嵌 HTML 无法渲染

  5. 5

    内容文件 front matter 需声明 outputs = ["Reveal"],幻灯片之间用上下留空行的 --- 分隔

查看仓库使用说明

授权与来源资料

使用条件与限制

免费使用 · 保留许可声明

本次收录的是公开仓库中采用 MIT 许可的免费版本;免费范围为该版本代码,不代表外部服务或第三方素材免费。

使用时需要遵守

  • 允许免费使用、修改、商用和分发该版本代码。
  • 分发代码副本或实质性部分时,保留原作者版权声明和完整 MIT 许可声明。
  • 代码按现状提供;担保与责任限制以原许可证及适用法律为准。

额外费用与待核对事项

  • 使用限制:最新版主题要求 Hugo 版本不低于 v0.93.0;若需兼容更早的 Hugo,只能改用较早的 release 版本。
  • 使用限制:默认从本地 static 目录加载 Reveal.js 以支持离线开发;若改用 CDN,需自行配置 reveal_cdn 并依赖外部 CDN 服务。
  • 使用限制:加载额外的 Reveal.js 插件时,必须自行把相应插件文件复制到 static 或 content 目录,主题不代为提供。
  • 使用限制:若要让 file:/// 本地文件 URL 正常工作,必须在 hugo.toml 中设置 relativeURLs 与 uglyURLs。
  • 使用限制:Hugo 低于 v0.42 时无法直接作为主题使用,需手动把 layouts、static 等文件复制到站点目录。
  • 演示图片、字体、图标及其他第三方素材需按各自许可核对,不能仅凭代码的 MIT 许可判断。
  • 域名、托管、数据库、支付或 AI 等外部服务可能另外收费。
查看原文依据

Permission is hereby granted, free of charge

许可证原文

⚠️ The latest version of this theme requires hugo version >= v0.93.0. If you need compatibility with an earlier version, try a previous release.

README 原文

To load from a CDN instead, set this value to `https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0` or whatever CDN you prefer.

README 原文

The appropriate files will need to have been copied into the `static` or content directory.

README 原文

If you need `file:///` URLs to work, make sure to set `relativeURLs` and `uglyURLs` in your `hugo.toml`.

README 原文

With hugo < v0.42, you have to manually copy a few files out of this theme into a few of your site's directories:

README 原文
https://github.com/joshed-io/reveal-hugo/blob/master/LICENSEhttps://github.com/joshed-io/reveal-hugo/blob/master/README.md

DeepSeek 根据仓库许可证和 README 整理 ·2026-10-02。结果仅覆盖已读取资料,依赖、图片、字体及后续条款变更以各自原文为准。

项目核对记录与介绍依据

模板资料

来源平台
Hugo Themes
资料与维护参考分
资料较完整 · 96 / 100
技术栈
Hugo · HTML
网站类型
启动器
这个分数如何计算

本站按许可资料(最高30分)、演示链接(12分)、预览图(10分)、Star数(15分)、记录的维护时间(15分)、描述完整度(8分)、功能记录(5分)和分类资料(5分)计算。它不是代码、安全或性能测试,也不是 Google 评分;有链接不代表已实测可用。

这个项目需要核对什么

记录的仓库更新时间
2026-05-19
截图检查日期
2026-10-02

已收录演示链接。请用你的内容与屏幕尺寸检查;有演示不代表表单、认证或支付已经可用。

目录记录的主要技术栈是 Hugo。请通过依赖清单和锁文件核对实际版本与托管要求。这些说明基于收录资料,不代表代码审计或部署实测。

查看具体选型方法 →

介绍的制作与核对状态

介绍由 AI 辅助整理目录与仓库资料。仓库作者不等于这篇介绍的审核者。

已完成服务器许可规则与 AI 来源核对;未经过人工编辑审核。

查看当时使用的来源资料

SHA-256: fafdda9d642d909b179c5f6f1f61aab73ab8efb44d5dda20c6834d45645cc8c2

2026-10-02T10:31:13.426Z

来源文件 / 仓库
# reveal-hugo

![License badge](https://img.shields.io/github/license/joshed-io/reveal-hugo.svg)
[![CircleCI](https://circleci.com/gh/joshed-io/reveal-hugo.svg?style=svg)](https://circleci.com/gh/joshed-io/reveal-hugo)
[![Website up/down badge](https://img.shields.io/website-up-down-green-red/https/reveal-hugo.dzello.com.svg)](https://reveal-hugo.dzello.com/)
![Last commit badge](https://img.shields.io/github/last-commit/joshed-io/reveal-hugo.svg)
[![Netlify Status](https://api.netlify.com/api/v1/badges/70c5c7a6-5fb2-40a9-98e1-20aa21336201/deploy-status)](https://app.netlify.com/sites/reveal-hugo/deploys)

A Hugo theme for [Reveal.js](https://revealjs.com/) that makes authoring and customization a breeze. With it, you can turn any properly-formatted Hugo content into a HTML presentation.

![screenshot of reveal-hugo](https://github.com/joshed-io/reveal-hugo/blob/master/images/screenshot.png?raw=true)

⚠️ The latest version of this theme requires hugo version >= v0.93.0. If you need compatibility with an earlier version, try a previous release.

## Example

Using reveal-hugo, presentations with multiple slides can be created with just one markdown file, like so:

```markdown
+++
title = "How to say hello"
+++

# English
Hello.

---

# Français
Salut.

---

# Español
Hola.
```

Just use `---` surrounded by blank lines to split content into different slides.

## Documentation

Visit [reveal-hugo.dzello.com](https://reveal-hugo.dzello.com/) to see a presentation created with this theme and learn about all of the different functionality available to you.

For a full-length blog post about reveal-hugo, checkout [Harness the Power of Static Site Generators to Create Presentations](https://forestry.io/blog/harness-the-power-of-static-to-create-presentations/) on the [Forestry.io blog](https://forestry.io/blog).

### Demos

Jump to the [exampleSite](exampleSite) folder in this repository to see the source code for the above presentation and several more. Here are links to those presentations live:

- [logo-example](https://reveal-hugo.dzello.com/logo-example/) - Shows how to add a logo to your presentation
- [custom-theme-example](https://reveal-hugo.dzello.com/custom-theme-example/) - Uses Hugo pipes to compile and use a custom Reveal.js SCSS theme (recommended!)
- [section-example](https://reveal-hugo.dzello.com/section-example/) - Very basic example that shows how to create a presentation for a Hugo section
- [plugin-example](https://reveal-hugo.dzello.com/plugin-example/) - Shows how to add additional Reveal.js plugins to your presentation, for example an image gallery
- [template-example](https://reveal-hugo.dzello.com/template-example/) - An example of using the slide shortcode with powerful templates
- [bundle-example](https://reveal-hugo.dzello.com/bundle-example/) - An example of creating a presentation from one or more markdown files in a leaf bundle
- [hugo-hl-example](https://reveal-hugo.dzello.com/hugo-hl-example/) - An example of using Hugo's compile-time syntax highlighter
- [highlightjs-linenumbers-example](https://reveal-hugo.dzello.com/highlightjs-linenumbers-example/) - An example of using the multiline and multi-step capabilities of highlight.js
- [blank Reveal-Hugo template](https://github.com/jerdog/reveal-hugo-template) - A templated skeleton site to get started quickly

### Starter repository

If you want to start creating a presentation right away, clone the [programming-quotes](https://github.com/joshed-io/programming-quotes) repository and start hacking.

## Tutorial: Create your first presentation

You should be able to complete this section with no prior knowledge of Hugo or Reveal.js. At the end, you'll have a working presentation with instant reloading.

### Create a hugo skeleton site

To start, [install Hugo](https://gohugo.io/getting-started/installing/) and create a new Hugo site:

```shell
hugo new site my-presentation
```

Change into the directory of the new site:

```shell
cd my-presentation
```

Initialize a git repository:

```shell
git init
```

### Get the `reveal-hugo` theme

#### Method 1 (recommended): use theme as hugo module

Turn your new skeleton site into a hugo module by issuing this command from site root:

```shell
hugo mod init github.com/me/my-presentation
```

- Declare the `reveal-hugo` theme module as a dependency of your site:

```
hugo mod get github.com/joshed-io/reveal-hugo
```

Open `hugo.toml` and add the following line:

```toml
theme = ["github.com/joshed-io/reveal-hugo"]
```

#### Method 2 (traditional): use theme as git submodule

Add the `reveal-hugo` theme as a submodule in the themes directory:

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

Open `hugo.toml` and add the following line:

```toml
theme = ["reveal-hugo"]
```

### Configure your presentation

Add some more contents to your `hugo.toml`:

```toml
[markup.goldmark.renderer]
unsafe = true

[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true
```
This tells Hugo to use the reveal-hugo theme and it registers a new output format called "Reveal".

Next, create a file in `content/_index.md` and add the following:

```markdown
+++
title = "My presentation"
outputs = ["Reveal"]
+++

# Hello world!

This is my first slide.
```

Back on the command line, run:

```shell
$ hugo server
```

Navigate to [http://localhost:1313/](http://localhost:1313/) and you should see your presentation.

![New site with reveal-hugo](https://github.com/joshed-io/reveal-hugo/blob/master/images/reveal-hugo-hello-world.png?raw=true)

To add more slides, just add content to `_index.md` or create new markdown files in `content/home`. Remember that each slide must be separated by `---` with blank lines above and below.

```markdown
# Hello world!

This is my first slide.

---

# Hello Mars!

This is my second slide.
```

### Cloning an existing repository (method 2 only)

If you have an existing repository that was setup with the above steps, you have to pull in the theme submodule after cloning your repository using the following command:

```shell
git submodule update --init
```

## Theme update (method 1 only)

When making use of `reveal-hugo` theme as hugo module, updating your theme is really easy:

At the command prompt, change to the root directory of your existing site.

```
cd /path/to/my-presentation
```

Then invoke hugo's module `get` subcommand with the update flag `-u`:

```
hugo mod get -u github.com/joshed-io/reveal-hugo
```

Hugo will automatically pull in the latest theme version. That's it, your update is done!

## Usage

The Usage guide is contained in the example presentation that lives in this repository in the [exampleSite](./exampleSite) directory. You can access a live version at [reveal-hugo.dzello.com](https://reveal-hugo.dzello.com/).

### Root vs. section presentations

Here's what the folder structure would look like with one root presentation and one section presentation.

```
- 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
```

This will create two presentations, one at `/` and one at `/ted-talk/`. The order that slides are appended to each can be controlled by the `weight` parameter specified in each file's front matter. The slides in `_index.md` will always come first, though you don't have to put any slides in there if you want to.

### Shortcodes

reveal-hugo comes with a variety of shortcodes that help you take advantage of some very useful Reveal.js features.

#### fragment shortcode

Wrap any content in the fragment shortcode and it will appear incrementally. Great for bulleted lists where you want one bullet point at a a time to appear.

```markdown
- {{% fragment %}}One{{% /fragment %}}
- {{% fragment %}}Two{{% /fragment %}}
- {{% fragment %}}Three{{% /fragment %}}
```

#### frag shortcode

Like fragment but more terse - content is placed inline in a self-closing shortcode.

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

#### slide shortcode

The slide shortcode lets you set custom HTML and Reveal.js attributes for each slide - things like id, class, transition, background just to name a few. The names are the same as Reveal.js but without the 'data-' prefix.

Add the shortcode above the slide content, below the `---` separator. Do not place content inside of the shortcode.

```markdown
---

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

# Hello, world!

---
```

Here's a list of documented slide attributes from the Reveal.js docs:

- `autoslide`
- `state`
- `background`
- `background-color`
- `background-image`
- `background-size`
- `background-position`
- `background-repeat`
- `background-opacity` (Opacity is on a 0-1 scale, by decimal. 0=transparent, 1=opaque.)
- `background-video`
- `background-video-loop`
- `background-video-muted`
- `background-interactive`
- `background-iframe`
- `background-transition`
- `transition` (can have different in and out transitions)
- `transition-speed`
- `notes` (can also use the note shortcode)
- `timing`

### Additional data attributes

Check MDN for information about how these attributes work.

- data-background-image - URL of the image to show. GIFs restart when the slide opens.
- data-background-size
- data-background-position
- data-background-repeat
- data-background-opacity

You can also pass through your own, a `data-` prefix will be added automatically to each one (except for `id` and `class`).

#### section shortcode

To create groups of slides that can be navigated vertically, surround your markdown with the section shortcode.

```markdown
{{% section %}}

# Vertical slide 1

---

# Vertical slide 2

{{% /section %}}
```

#### note shortcode

Add [speaker notes](https://github.com/hakimel/reveal.js/#speaker-notes) for each slide with the note shortcode.

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

*💡 Tip: you can also add notes by adding a `note` attribute to the slide shortcode.*

#### markdown shortcode

Markdown surrounded by the markdown shortcode will not be rendered by Hugo but by Reveal.js itself. This is useful if you want to use some native Reveal.js markdown syntax that isn't supported by reveal-hugo.

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

### Maths and equations (via `MathJax`)

### Option 1: `math` code block

You can author your equation inside a `math` [code block](https://reveal-hugo.dzello.com/#/math-equations):

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

Use of the code block will automatically activate needed `MathJax` script for equation display.

If you want to use inline equations (like $E=mc^2$) wrap your math content in two single-\$:

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

If you want to use inline equations and no `math` code block for auto activation is present in your slides, you need to manually enable `MathJax` by setting the parameter `math` to `true` in your page frontmatter.

### Option 2: `math` shortcode

Alternatively, you can author your equation inside a `math` [shortcode](https://reveal-hugo.dzello.com/#/math-shortcode):

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

Use of the shortcode will automatically activate needed `MathJax` script for equation display.

For inline equations (like $E=mc^2$) use the self closing form of the `math` shortcode:

```markdown
Albert Einstein's famous formula: {{< math "E=mc^2" />}}
```
For the sake of brevity, the inline content can be given as unnamed first shortcode parameter, as in the code fragment above. In a more concise form, the math content can also be assigned to a named shortcode parameter `inline`: `{{< math inline="E=mc^2" />}}`.

### HTML slides

If you need to create fancier HTML for a slide than you can do with markdown, just add `data-noprocess` to the &lt;section&gt; element.

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

### Reusable slides and sections

Sometimes you need to reuse a slide in the same presentation or across different presentations. reveal-hugo makes use of Hugo data templates to make both cases easy.

To create reusable slides, create a TOML (or JSON or YAML) file in your site's data directory. Give it a name that reflects its content or just `slides.toml`. In that file, add a key for each reusable slide. The name should reflect the slide's content and the value should be the slide's markdown.

```toml
thankyou = '''

# Thank you!

Any questions?

'''
```

*💡 Tip: TOML's multiline string syntax comes in handy here, note the '''.*

Each key can contain **one or more** slides separated by `---` and newlines. That way you can create reusable sections.

```toml
thankyou = '''

# Thank you!

---

Any questions?

'''
```

To render a slide from a data template, use the slide shortcode with a content attribute:

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

The part before the "." is the name of the file in the data directory. The part after the dot is the key to look up in that file.

You can use all the additional slide shortcode attributes. They will be applied to every slide in the data template.

## Configuration

Customize the Reveal.js presentation by setting these values in `hugo.toml` or the front matter of any presentation's `_index.md` file.

- `reveal_hugo.theme`: The Reveal.js theme used; defaults to "black"
- `reveal_hugo.custom_theme`: The path to a locally hosted Reveal.js theme in the static or assets folder
- `reveal_hugo.custom_theme_compile`: If set to true, the theme will be compiled with Hugo pipes (and must live in the assets folder)
- `reveal_hugo.custom_theme_options`: Provide a dictionary to customize theme compilation, see [Hugo's SCSS docs](https://gohugo.io/hugo-pipes/scss-sass/#options) for a list of options
- `reveal_hugo.highlight_theme`: The [highlight.js](https://highlightjs.org/) theme used; defaults to "default"
- `reveal_hugo.reveal_cdn`: The location to load Reveal.js files from; defaults to the `reveal-js` folder in the static directory to support offline development. To load from a CDN instead, set this value to `https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.7.0` or whatever CDN you prefer.
- `reveal_hugo.highlight_cdn`: The location to load highlight.js files from; defaults to to the `highlight-js` folder in the static directory to support offline development. To load from a CDN instead, set this value to `https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0` or whatever CDN you prefer.
- `reveal_hugo.load_default_plugins`: If set to true (default), the plugins included by default are loaded. These are markdown, highlight.js, notes and zoom.
- `reveal_hugo.plugins`: (see below) An array of additional Reveal.js plugins to load. The appropriate files will need to have been copied into the `static` or content directory. See here for a [big list of plugins](https://github.com/hakimel/reveal.js/wiki/Plugins,-Tools-and-Hardware) you can try. The original implementation used to accept an array of javascript files (e.g. `["plugin/gallery/gallery.plugin.js"]`), but now reveal-hugo can fully load plugin javascript and css. To enable this mode, You need to provide an array of plugin definition objects with `name`, `source` and an optional `css`, `verbatim` and `order` fields. Reveal-hugo will try to load the plugins at the path specified by `source`. If `verbatim=true` is used, the path is tried as-is. Otherwise, the path is resolved from the content dir or `static` dir. Finally, the `reveal_cdn` is prepended to the path if no other conditions are satisfied. The `order` field controls the order of javascript loading and will seldomly used. See [plugin-example](https://reveal-hugo.dzello.com/plugin-example/) for a plugin walkthrough.

This is how parameters will look in your `hugo.toml`:

```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.
```

Or in the front matter of an `_index.md` file:

```TOML
[reveal_hugo]
theme = "moon"

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

```

Include any other attributes in those sections that you'd like to be fed as arguments to `Reveal.initialize` in **snakecase**, so `slide_number` instead of `slideNumber`. Params are converted from snakecase to camelcase before passing to Reveal.js. This is necessary to maintain the proper case of the parameters.

Here's an example of configuring Reveal.js parameters alongside a theme and highlight.js theme:

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

See the [extensive list of Reveal.js configuration options](https://github.com/hakimel/reveal.js/#configuration) here.

### Syntax highlighting

Syntax highlighting can be done with Hugo at compile-time or using Reveal.js with the pre-installed highlight.js plugin. Presentations can use both if they wish for different pieces of code.

To do highlighting with Hugo, use the [highlight shortcode](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) and check out the [hugo-hl-example](https://reveal-hugo.dzello.com/hugo-hl-example/) example presentation.

To see an example of highlighting with Reveal.js, check out the [highlightjs-linenumbers-example](https://reveal-hugo.dzello.com/highlightjs-linenumbers-example/) presentation.

By default, markdown code fences will be processed with Hugo. To turn that off, add this to your `hugo.toml` file:

``` toml
[markup.highlight]
codeFences = false
```

Now, the code in the fences will be highlighted by highlight.js instead.

### Custom Reveal.js themes

If you have a custom reveal theme to use (in .css form), place it in the `static` folder and specify it in the configuration. For example, if your css file lives here:

```
| static
  | stylesheets
    - custom-theme.css
```

Then this is what you'll put in `hugo.toml`:

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

### Compiling a custom Reveal.js theme with Hugo pipes

Reveal.js theme customization is easiest to do by overriding variables in the SCSS or PostCSS build process. You can take advantage of Hugo pipes to do the theme compilation. In this case, your SCSS, Saas or PostCSS file needs to live in assets:

```
| assets
  | stylesheets
    - custom-theme.scss
```

If you just wanted to change the presentation colors, here's what you might put in `custom-theme.scss`:

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

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

To learn more about Reveal.js theme customization, check out the [Reveal.js theme docs](https://github.com/hakimel/reveal.js/blob/master/css/theme/README.md).

This is what the front matter would look like:

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

You can also add options that will be passed to [Hugo's toCSS method](https://gohugo.io/hugo-pipes/scss-sass/#options):

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

Check out the [custom-theme-example presentation](https://reveal-hugo.dzello.com/custom-theme-example/) to see a working example.

## Adding HTML to the layout

If you need to add something to the HTML layout, you can create partials that live at specific locations, depending on which presentation you want to customize and where you want the HTML inserted into the page.

| Presentation | Before &lt;/head&gt;            | Before &lt;/body&gt;            | Before closing &lt;/div&gt; of `div.reveal` |
|--------------|---------------------------------|---------------------------------|---------------------------------------------|
| All          | reveal-hugo/head.html           | reveal-hugo/body.html           | reveal-hugo/end.html                        |
| Root         | home/reveal-hugo/head.html      | home/reveal-hugo/body.html      | home/reveal-hugo/end.html                   |
| Section      | {section}/reveal-hugo/head.html | {section}/reveal-hugo/body.html | {section}/reveal-hugo/end.html              |

This is the recommended way to add custom CSS and JavaScript to each presentation.

> 💡 Tip: In Hugo, partials live in the `layouts` folder:
>
> For example, if you have HTML that is to be placed before every presentation, this would be the structure:
> ```
> - layouts
>   - partials
>     - reveal-hugo
>       - head.html
>       - body.html
>       - end.html

## Offline development

Offline-friendly development is the default. The Reveal.js and Highlight.js files are loaded from the static directory by default. (See above for how to use a CDN instead). If you need `file:///` URLs to work, make sure to set `relativeURLs` and `uglyURLs` in your `hugo.toml`.

```toml
relativeURLs = true
uglyURLs = true
```

Note: `uglyURLs` isn't strictly required, but it is useful if you're loading against the filesystem as it makes sure that all URLs end in .html and links point directly at them instead of to a folder.



## Tutorial: Add a Reveal.js presentation to an existing Hugo site

If your Hugo site already has a theme but you'd like to create a presentation from some of its content, that's very easy.

### Get the `reveal-hugo` theme

#### Method 1 (recommended): use theme as hugo module

On your site root, check for the existence of a file `go.mod` which marks your site as hugo module.
If this file is not present yet, create it by issuing this command from site root:

```shell
hugo mod init github.com/me/my-presentation
```

- Declare the `reveal-hugo` theme module as a dependency of your site:

```
hugo mod get github.com/joshed-io/reveal-hugo
```

Open `hugo.toml`, look for the line `theme = ...` and add `reveal-hugo` to your site's array of themes :

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

#### Method 2 (traditional): use theme as git submodule

Add the `reveal-hugo` theme as a submodule in the themes directory:

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

Open `hugo.toml`, look for the line `theme = ...` and add `reveal-hugo` to your site's array of themes :

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

#### Note: Use of Hugo versions below 0.42

With hugo < v0.42, you have to manually copy a few files out of this theme into a few of your site's directories:

```shell
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 ../../
```

Files and directories are named such that they shouldn't conflict with your existing content. Of course, you should double check before copying, especially the shortcodes which can't be put under a directory.

### Configure your site for presentations

Next, add the Reveal output format to your site's `hugo.toml` file

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

Now you can add `outputs = ["Reveal"]` to the front matter of any section's `_index.md` file and that section's content will be combined into a presentation and written to `index.html`. If you already have a `index.html` page for that section, just change the `baseName` above to `reveal` and the presentation will be placed in a `reveal.html` file instead.

Note: If you specify `outputs = ["Reveal"]` for a single content file, you can prevent anything being generated for that file. This is handy if you other default layouts that would have created a regular HTML file from it. Only the list file is required for the presentation.

## Recipes

### Create a presentation from a leaf bundle or single page type

By default, reveal-hugo doesn't create presentations for single pages (i.e. pages other than `_index.md`) as it assumes those pages are pieces of a larger presentation in the section starting with `_index.md`. This might not be the case if your content is structured in a leaf bundle (the main file is then `index.md` with no underscore, which Hugo treats as a single page) or if you just want to put a presentation in a single file, say `presentation.md`. In these cases, you just need to tell Hugo to use a different layout.

If you're using a leaf page bundle, set the following in the front matter of the `index.md` file:

```toml
layout = "bundle"
```

If you're in a single page file like `presentation.md`, set the following in the front matter:

```toml
layout = "list"
```

### Create a page that lists out all presentations

See [this issue](https://github.com/joshed-io/reveal-hugo/issues/37) for a template that you can use.

## Reveal.js tips

These are some useful Reveal.js features and shortcuts.

- 's' - type 's' to enter speaker mode, which opens a separate window with a time and speaker notes
- 'o' - type 'o' to enter overview mode and scroll through slide thumbnails
- 'f' - type 'f' to go into full-screen mode

Here are a few useful Reveal.js-related tools:

- [decktape](https://github.com/astefanutti/decktape) for exporting a presentation as a PDF
- More [revealjs themes](https://github.com/joshed-io/revealjs-themes) including robot-lung and sunblind

Find many more on the Reveal.js wiki: [Plugins, tools and hardware](https://github.com/hakimel/reveal.js/wiki/Plugins,-Tools-and-Hardware).

## Implementations

Have you built something with reveal-hugo? Add a link to it here.

- [dzello's Paris Wedding Weekend Guide](https://estelle.and.dzello.com/guide/) ([source](https://github.com/dzello/estelle-and-josh/blob/master/site/content/guide/_index.md))
- [DevOps Training](https://devops.training.barpilot.io/) ([source](https://github.com/guilhem/devops-training))
- [Personal CV](https://www.pablomarcos.me/es/presentations/mi-cv/#/), [Master Thesis](https://www.pablomarcos.me/es/presentations/cangraph/#/), [Master Thesis Update for the WHO](https://www.pablomarcos.me/es/presentations/cangraph-update/) & [Proposal for New Bus Services in Madrid](https://www.pablomarcos.me/es/presentations/alegaciones-crtm/#/) by Pablo Marcos


## Changelog

- 2018-08-03: The slide shortcode is now easier to use. An auto-closing version sits inside the slide instead of needing to surround its content and add a closing tag.

## Contributing

Contributions are very welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
反馈内容错误

看看同类模板

对比同技术栈与用途的模板,找到更适合的视觉与内容结构。