themen-hugo-35c3-reveal/README.md

190 lines
5.9 KiB
Markdown
Raw Normal View History

2018-04-26 17:25:43 -05:00
# reveal-hugo
2018-04-30 14:58:55 -05:00
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.
2018-04-26 17:25:43 -05:00
2018-04-30 13:04:48 -05:00
![screenshot of reveal-hugo](/images/screenshot.png)
2018-04-26 18:12:22 -05:00
### Example
2018-04-30 14:58:55 -05:00
Using reveal-hugo, presentations with multiple slides can be created with just one markdown file, like so:
2018-04-26 18:12:22 -05:00
```markdown
2018-04-30 14:58:55 -05:00
+++
title = "How to say hello"
+++
2018-04-26 18:12:22 -05:00
# English
Hello.
---
# Français
Salu.
---
# Espagñol
Hola.
```
2018-04-30 14:58:55 -05:00
Just use `---` to split content into different slides.
2018-04-26 18:12:22 -05:00
2018-04-28 01:31:21 -05:00
## Demo
2018-04-26 18:12:22 -05:00
2018-04-30 14:58:55 -05:00
Visit [https://dzello.com/reveal-hugo/](https://dzello.com/reveal-hugo/) to see a presentation created with this theme and learn more about what you can do.
2018-04-26 18:12:22 -05:00
2018-04-30 14:58:55 -05:00
## Tutorial
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.
2018-04-26 18:12:22 -05:00
2018-04-28 01:31:21 -05:00
### Create your first presentation
To start, [install Hugo](https://gohugo.io/) and create a new Hugo site:
2018-04-27 01:20:05 -05:00
```shell
$ hugo new site my-presentation
```
2018-04-27 01:37:02 -05:00
Change into the directory of the new site:
2018-04-27 01:20:05 -05:00
```shell
2018-04-27 01:37:02 -05:00
$ cd my-presentation
2018-04-27 01:20:05 -05:00
```
2018-04-28 01:31:21 -05:00
Clone the reveal-hugo theme into the themes directory:
2018-04-27 01:20:05 -05:00
```shell
2018-04-27 01:37:02 -05:00
$ git clone git@github.com:dzello/reveal-hugo.git themes/reveal-hugo
2018-04-27 01:20:05 -05:00
```
2018-04-28 01:31:21 -05:00
Open `config.toml` and add the following contents:
2018-04-27 01:20:05 -05:00
```toml
2018-04-28 01:31:21 -05:00
theme = "reveal-hugo"
[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true
2018-04-27 01:20:05 -05:00
```
2018-04-28 01:31:21 -05:00
This tells Hugo to use the reveal-hugo theme and it registers a new output format called "Reveal".
2018-04-28 01:31:21 -05:00
Next, create a file in `content/_index.md` and add the following:
```markdown
2018-04-27 01:20:05 -05:00
+++
title = "My presentation"
outputs = ["Reveal"]
2018-04-27 01:20:05 -05:00
+++
# Hello world!
This is my first slide.
```
Back on the command line, run:
```shell
2018-04-28 01:31:21 -05:00
$ hugo server
2018-04-27 01:20:05 -05:00
```
2018-04-28 01:31:21 -05:00
Navigate to [http://localhost:1313/](http://localhost:1313/) and you should see your presentation.
2018-04-27 01:20:05 -05:00
2018-04-27 01:28:29 -05:00
![New site with reveal-hugo](/images/reveal-hugo-hello-world.png)
2018-04-28 01:31:21 -05:00
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.
2018-04-27 01:37:02 -05:00
```markdown
2018-04-28 01:31:21 -05:00
# Hello world!
This is my first slide.
2018-04-27 01:37:02 -05:00
---
# Hello Mars!
2018-04-28 01:31:21 -05:00
This is my second slide.
2018-04-27 01:37:02 -05:00
```
2018-04-30 14:58:55 -05:00
## Usage
2018-04-26 18:12:22 -05:00
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 [https://dzello.com/reveal-hugo/](https://dzello.com/reveal-hugo/).
2018-04-26 18:12:22 -05:00
2018-04-30 14:58:55 -05:00
## Configuration
2018-04-28 01:31:21 -05:00
Customize the Reveal.js presentation by setting these values in `config.toml` or the front matter of any presentation's `index.md` file.
2018-04-26 18:12:22 -05:00
2018-04-30 14:58:55 -05:00
- `params.reveal_hugo.theme`: The Reveal.js theme used, defaults to "black"
- `params.reveal_hugo.highlight_theme`: The [highlight.js](https://highlightjs.org/) theme used, defaults to "default"
2018-04-26 18:12:22 -05:00
Include any other attributes in `params.reveal_hugo` that you'd like to be fed as arguments to `Reveal.initialize` in **snakecase**. So `slideNumber` becomes `slide_number`. The reason is that Hugo lowercases all params and Reveal.js is case-sensitive. Params are converted from snakecase to camelcase before passing to Reveal.js.
See the [extensive list of Reveal.js configuration options](https://github.com/hakimel/reveal.js/#configuration) here. The defaults used by this theme are located in `data/reveal_hugo.toml`.
2018-04-26 18:43:52 -05:00
2018-04-30 14:58:55 -05:00
If you're new to TOML, this is how it should look in your `config.toml`:
2018-04-26 18:43:52 -05:00
2018-04-30 14:58:55 -05:00
```TOML
[params.reveal_hugo]
theme = "moon"
```
2018-04-30 14:58:55 -05:00
Or in the front matter of an `_index.md` file:
2018-04-30 14:58:55 -05:00
```TOML
[reveal_hugo]
theme = "moon"
2018-04-27 00:50:08 -05:00
```
## Adding HTML to the page
2018-04-30 14:58:55 -05:00
If you need to add something to the HTML page, just override one or both of the empty partials that live at `layouts/partials/reveal-hugo/body.html` and `layouts/partials/reveal-hugo/head.html`. These partial are injected into the page just before the closing of the body and head tags respectively. Common uses would be to add custom CSS or JavaScript to your presentation.
2018-04-30 14:58:55 -05:00
2018-04-28 01:35:27 -05:00
### 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. First, manually copy a few files out of this theme into a few of your site's directories:
```shell
cd my-hugo-site
git clone git@github.com:dzello/reveal-hugo.git themes/reveal-hugo
cd themes/reveal-hugo
cp -r data layouts static ../../
```
2018-04-30 14:58:55 -05:00
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.
Next, add the Reveal output format to your site's `config.toml` file
```toml
[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true
```
2018-04-28 01:35:27 -05:00
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.
2018-04-28 01:35:27 -05:00
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.
2018-04-30 18:15:04 -05:00
# Miscellaneous
Not directly related to reveal-hugo, but these are some of my favorite Reveal.js features and shortcuts.
- 's' - type 's' to enter speaker mode, which opens a separate window with a time and speaker notes
2018-05-01 01:06:57 -05:00
- 'o' - type 'o' to enter overview mode and scroll through slide thumbnails
2018-04-30 18:15:04 -05:00
- 'f' - type 'f' to go into full-screen mode
2018-04-30 02:38:42 -05:00
# Contributing
2018-04-30 14:58:55 -05:00
Contributions are very welcome. To run the example site in this repository locally, clone this repository and run:
2018-04-30 02:38:42 -05:00
```shell
hugo server -s exampleSite -d ../public --themesDir '../' --theme '.'
```
or simply...
```shell
npm start
```