commit f5b05358a8f55f7c69926680691758aa01535d10 Author: pgp Date: Wed Jan 5 23:28:57 2022 +0100 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..55ec008 --- /dev/null +++ b/README.md @@ -0,0 +1,589 @@ +# reveal-hugo + +![License badge](https://img.shields.io/github/license/dzello/reveal-hugo.svg) +[![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/dzello/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/dzello/reveal-hugo/blob/master/images/screenshot.png?raw=true) + +## 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 + +### Starter repository + +If you want to start creating a presentation right away, clone the [programming-quotes](https://github.com/dzello/programming-quotes) repository and start hacking. + +## 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. + +### Create your first presentation + +To start, [install Hugo](https://gohugo.io/) 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 +``` + +Add the reveal-hugo theme as a submodule in the themes directory: + +```shell +git submodule add git@github.com:dzello/reveal-hugo.git themes/reveal-hugo +``` + +Open `config.toml` and add the following contents: + +```toml +theme = "reveal-hugo" + +[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/dzello/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 + +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 +``` + +## 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-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` + +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 %}} +``` + +### MathJax support + +Add the following to `layouts/partials/reveal-hugo/body.html`: + +``` + + + +``` + +Then you can do this in a slide: + +``` +## Cool equations + +Displayed equations are wrapped in double-\$ + +$$\frac{n!}{k!(n-k)!} = \binom{n}{k}$$ + +Inline equations like $E=mc^2$ are wrapped in single-\$ +``` + +### HTML slides + +If you need to create fancier HTML for a slide than you can do with markdown, just add `data-noprocess` to the <section> element. + +```html +
+

Hello, world!

+
+``` + +### 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 `config.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`: An array of additional Reveal.js plugins to load, e.g. `["plugin/gallery/gallery.plugin.js"]`. The appropriate files will need to have been copied into the `static` directory. CDN loading is not supported. See here for a [big list of plugins](https://github.com/hakimel/reveal.js/wiki/Plugins,-Tools-and-Hardware) you can try. + +This is how parameters will look in your `config.toml`: + +```TOML +[params.reveal_hugo] +theme = "moon" +``` + +Or in the front matter of an `_index.md` file: + +```TOML +[reveal_hugo] +theme = "moon" +``` + +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, checs 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 `config.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 `config.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/css/theme/template/mixins"; +@import "../reveal-js/css/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 </head> | Before </body> | Before closing </div> 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 `config.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. + +## Recipes + +### 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 https://github.com/dzello/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. + +Next, add the Reveal output format to your site's `config.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. + +**Tip**: As of Hugo 0.42, Hugo [has theme inheritence](https://gohugo.io/news/0.42-relnotes/). You can avoid the file copying step above by adding `"reveal-hugo"` to your site's array of themes. + +### 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/dzello/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/dzello/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)) + + +## 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. diff --git a/archetypes/default.md b/archetypes/default.md new file mode 100644 index 0000000..00e77bd --- /dev/null +++ b/archetypes/default.md @@ -0,0 +1,6 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +date: {{ .Date }} +draft: true +--- + diff --git a/assets/custom-theme.scss b/assets/custom-theme.scss new file mode 100644 index 0000000..4f8462a --- /dev/null +++ b/assets/custom-theme.scss @@ -0,0 +1,35 @@ +@import "reveal-js/css/theme/template/mixins"; +@import "reveal-js/css/theme/template/settings"; + +$backgroundColor: rgb(3, 129, 45); + +$mainColor: #fff; +$headingColor: #fff; + +$mainFontSize: 38px; +$mainFont: 'Source Sans Pro', Helvetica, sans-serif; +$headingFont: 'Source Sans Pro', Helvetica, sans-serif; +$headingTextShadow: none; +$headingLetterSpacing: normal; +$headingTextTransform: uppercase; +$headingFontWeight: 600; +$linkColor: #42affa; +$linkColorHover: lighten( $linkColor, 15% ); +$selectionBackgroundColor: lighten( $linkColor, 25% ); + +$heading1Size: 2.5em; +$heading2Size: 1.6em; +$heading3Size: 1.3em; +$heading4Size: 1.0em; + +@import "reveal-js/css/theme/template/theme"; + +section.has-light-background { + &, h1, h2, h3, h4, h5, h6 { + color: #222; + } +} + +.reveal pre { + margin: 50px auto; +} diff --git a/config.toml b/config.toml new file mode 100644 index 0000000..8ef894a --- /dev/null +++ b/config.toml @@ -0,0 +1,36 @@ +baseURL = "/" +languageCode = "en-us" +title = "A Hugo theme for creating Reveal.js presentations" +disableKinds = ["sitemap", "RSS"] +theme = "reveal-hugo" + +# uncomment for browsing at file:/// +relativeURLs = true +uglyURLs = true + +[author] +name = "Josh Dzielak" + +# currently only the unsafe mode for goldmark is supported +[markup.goldmark.renderer] +unsafe = true + +# choose between Hugo compile-time or Highlight.js +# syntax highlighting for code inside of code fences +[markup.highlight] +codeFences = false # use highlight.js +# codeFences = true # use hugo highlighting at compile time +style = "tango" # set a style for hugo highlighting + +[outputFormats.Reveal] +baseName = "index" +mediaType = "text/html" +isHTML = true + +[params.reveal_hugo] +history = true + +# used in content/template-example +[params.reveal_hugo.templates.grey] +background = "#424242" +transition = "convex" diff --git a/content/_index.md b/content/_index.md new file mode 100644 index 0000000..fba3be6 --- /dev/null +++ b/content/_index.md @@ -0,0 +1,22 @@ ++++ +title = "reveal-hugo" +description = "A Hugo theme for creating Reveal.js presentations" +outputs = ["Reveal"] +[reveal_hugo] +custom_theme = "reveal-hugo/themes/robot-lung.css" +margin = 0.2 +highlight_theme = "color-brewer" +transition = "slide" +transition_speed = "fast" +[reveal_hugo.templates.hotpink] +class = "hotpink" +background = "#FF4081" ++++ + +# πŸ“½οΈ + +# reveal-hugo + +A Hugo theme for creating Reveal.js presentations. + +~ made by [@dzello](https://dzello.com/) ~ \ No newline at end of file diff --git a/content/bundle-example/continued.md b/content/bundle-example/continued.md new file mode 100644 index 0000000..b2a4381 --- /dev/null +++ b/content/bundle-example/continued.md @@ -0,0 +1,16 @@ ++++ ++++ + +If more markdown files are present in the bundle, their contents will be added to the presentation. + +--- + +Specify `weight` in the frontmatter if it's necessary to order them. + +--- + +If you don't want them to be included, specify `layout = "list"` in the front matter instead of `layout = "bundle"`. + +--- + +## THE END \ No newline at end of file diff --git a/content/bundle-example/index.md b/content/bundle-example/index.md new file mode 100644 index 0000000..087bffe --- /dev/null +++ b/content/bundle-example/index.md @@ -0,0 +1,30 @@ ++++ +title = "Bundle example presentation" +outputs = ["Reveal"] +layout = "bundle" +[reveal_hugo] +theme = "night" +margin = 0.2 ++++ + +# Page Bundles + +--- + +[Hugo page bundles](https://gohugo.io/content-management/page-bundles/) are a useful way to organize content. + +--- + +To create a reveal-hugo presentation from the `index.md` file of a leaf page bundle, you need to specify the layout manually. + +```toml +layout = "bundle" +``` + +--- + +Why? By default, reveal-hugo doesn't create pages for single template types (foo.md), only for list template types (_index.md). + +--- + +This technique can also be used to output an HTML file for any section of a presentation, should you need to. diff --git a/content/custom-theme-example/_index.md b/content/custom-theme-example/_index.md new file mode 100644 index 0000000..dd09946 --- /dev/null +++ b/content/custom-theme-example/_index.md @@ -0,0 +1,74 @@ ++++ +title = "Custom theme example presentation" +outputs = ["Reveal"] +[reveal_hugo] +custom_theme = "custom-theme.scss" +custom_theme_compile = true ++++ + +## πŸ–Œ ️ + +## Custom Themes + +*with Hugo Pipes* + +--- + +This presentation uses a custom Reveal.js theme written in SCSS that is compiled by Hugo, using [Hugo pipes](https://gohugo.io/hugo-pipes/). + +--- + +Hugo pipes compiles the source code of the theme, located in `assets/custom-theme.scss`, into CSS. + +--- + +## πŸ˜„ + +No separate build process is required, which means you can iterate on your theme and your content at the same time. + +--- + +To set a custom theme and use Hugo to compile it: + +```toml +[reveal_hugo] +custom_theme = "custom-theme.scss" +custom_theme_compile = true +``` + +`custom-theme.scss` must live in the `assets` folder. + +--- + +To pass compilation options, use the `custom_theme_options` param: + +```toml +[reveal_hugo.custom_theme_options] +targetPath = "css/custom-theme.css" +enableSourceMap = true +``` + +See all the [available options](https://gohugo.io/hugo-pipes/scss-sass/#options). + +--- + +Note: to use a custom theme that doesn't need compilation, put it in the `static` directory and do not set the `custom_theme_compile` parameter. It will be served to the browser directly. + +--- + +Write a custom Reveal.js theme in four steps: + +```text +1. Import `mixins` and `settings` from the templates directory +2. Override variables and functions for colors, fonts and sizes +3. Import `theme` from the templates directory +4. Add any additional selectors to override the built CSS +``` + +--- + +See the [Reveal.js theme docs](https://github.com/hakimel/reveal.js/blob/master/css/theme/README.md) to learn what overrides are possible. + +--- + +See `assets/custom-theme.scss` or any file in `assets/reveal-js/css/theme/source` for an example. diff --git a/content/extending-layout-example/_index.md b/content/extending-layout-example/_index.md new file mode 100644 index 0000000..108d840 --- /dev/null +++ b/content/extending-layout-example/_index.md @@ -0,0 +1,53 @@ ++++ +title = "Extend layout with configuration" +outputs = ["Reveal"] +[reveal_hugo] +theme = "night" +margin = 0.2 +custom_css = "css/custom.css" +custom_js = "js/custom.js" ++++ + +### Extending an existing layout + +If you are using an existing theme and you want to a specific CSS class or add a dynamic function using javascript. It is possible to extend existing layout. + +--- + +### Extending CSS + +You can use `partials` or you can specify `custom_css` in your configuration : + +```toml +[reveal_hugo] +custom_css = "css/custom.css" +``` + +The `custom.css` can be present in `static/css/custom.css` + + +--- + +### Extending with javascript + +Same as CSS you can extend your presentation with javascript using `partials` or with `custom_js` in your configuration: + +```toml +[reveal_hugo] +custom_js = "js/custom.js" +``` + + +The `custom.js` can be present in `static/js/custom.js` + + +--- + +{{< slide class="custom" id="customjs" >}} +## Extend layout example +Here the slide has an additional css class `custom` using `slide` *shortcode*. This class is hosted in a custom CSS. + +If you click on this text background-color will using a custom javascript file. + + + diff --git a/content/highlightjs-linenumbers-example/_index.md b/content/highlightjs-linenumbers-example/_index.md new file mode 100644 index 0000000..a285336 --- /dev/null +++ b/content/highlightjs-linenumbers-example/_index.md @@ -0,0 +1,160 @@ ++++ +title = "Reveal.js 3.9.0 highlighting example" +outputs = ["Reveal"] + +[reveal_hugo] +theme = "white" +highlight_theme = "vs" ++++ + +## Multiline highlighting with Highlight.js + +--- + +This presentation shows the use of the [new highlighting features](https://github.com/hakimel/reveal.js/blob/master/README.md#step-by-step-highlights) which were introduced with Reveal.js [v3.9.0](https://github.com/hakimel/reveal.js/releases/tag/3.9.0). + +--- + +## Prerequisite + +Disable `codeFences` in to your `config.toml` to prevent Hugo's built-in highlighting for code inside of `---` fences. + +{{< highlight toml "style=github" >}} +[markup.highlight] +codeFences = false +{{< /highlight >}} + +--- + +## Theme + +Specify a theme for Highlight.js in `config.toml` + +{{< highlight toml "style=github" >}} +[params.reveal_hugo] +highlight_theme = "github" +{{< /highlight >}} + +--- + +...or in the `_index.md` front matter + +{{< highlight toml "style=github" >}} +[reveal_hugo] +highlight_theme = "github" +{{< /highlight >}} + +--- + +## Usage + +The line highlighting is configured by adding `{}` immediately after the language selection of the markdown code block. + +{{< highlight md >}} +```foo{} + +``` +{{< /highlight >}} + +--- + +## Just line numbers + +`{}` + +{{< highlight md >}} +```go{} +package main +import "fmt" +func main() { + fmt.Println("Hello world!") +} +``` +{{< /highlight >}} + +```go{} +package main +import "fmt" +func main() { + fmt.Println("Hello world!") +} +``` + +--- + +## Highlight specific lines + +`{}` + +{{< highlight md >}} +```go{1,3-5} +package main +import "fmt" +func main() { + fmt.Println("Hello world!") +} +``` +{{< /highlight >}} +```go{1,3-5} +package main +import "fmt" +func main() { + fmt.Println("Hello world!") +} +``` + +--- + +## Multi step highlight + +`{}` + +{{< highlight md >}} +```go{1|2|3-5} +package main +import "fmt" +func main() { + fmt.Println("Hello world!") +} +``` +{{< /highlight >}} + +```go{1|2|3-5} +package main +import "fmt" +func main() { + fmt.Println("Hello world!") +} +``` +--- + +## Hiding the line numbers + +There is no Reveal.js parameter to use line highlighting *without* line numbers. +However it can be achieved by adding the some [custom CSS](https://github.com/dzello/reveal-hugo#adding-html-to-the-layout). + +{{< highlight html "style=github" >}} + +{{< /highlight >}} + +--- + +πŸ’‘ Put the custom CSS in either of these partials: + +```text +# for all presentations +layouts/partials/reveal-hugo/body.html +``` + +```text +# for one presentation +layouts/partials/{presentation-name}/reveal-hugo/body.html +``` + +--- + +Thanks! \ No newline at end of file diff --git a/content/home/configuration.md b/content/home/configuration.md new file mode 100644 index 0000000..1d13e9b --- /dev/null +++ b/content/home/configuration.md @@ -0,0 +1,170 @@ ++++ +weight = 21 ++++ + +# Configuration + +Place configuration values in `config.toml` or a presentation's front matter (`_index.md`). + +--- + +## Reveal.js themes + +Themes control the look and feel of your presentation. Set the `theme` param to any [valid Reveal.js theme](https://github.com/hakimel/reveal.js/#theming). + +```toml +[params.reveal_hugo] +theme = "moon" +``` + +--- + +## Use a custom theme + +To use a custom Reveal.js theme, place the CSS file in the `static` directory and set the `custom_theme` param. + +```toml +[params.reveal_hugo] +custom_theme = "reveal-hugo/themes/robot-lung.css" +``` + +--- + +### Use a custom theme (advanced) + +To use Hugo pipes to build a custom Reveal.js theme, place the source file (SCSS / PostCSS) in the `assets` directory and set the `custom_theme_compile` param. + +```toml +[params.reveal_hugo] +custom_theme = "reveal-hugo/themes/custom-theme.scss" +custom_theme_compile = true +``` + + + +πŸ’‘ See the [custom theme example presentation](/custom-theme-example/) for more details. + + + +--- + +## Bundled themes + +reveal-hugo comes with 2 extra Reveal.js themes: + +- [robot-lung](https://github.com/dzello/revealjs-themes#robot-lung) (this one) +- [sunblind](https://github.com/dzello/revealjs-themes#sunblind) + +
+ + + +They live in the `static/reveal-hugo/themes` folder and also [on Github](https://github.com/dzello/revealjs-themes). + + + +--- + +## Reveal.js params + +Set **snakecase** versions of Reveal.js params, which will be camelized and passed to `Reveal.initialize`. + +```toml +[params.reveal_hugo] +history = true +slide_number = true +transition = 'zoom' +transition_speed = 'fast' +``` + +[Full list of params](https://github.com/hakimel/reveal.js/#configuration) + +--- + +## highlight.js themes + +To change the syntax highlighting theme, set the `highlight_theme` +to a valid [highlight.js theme name](https://highlightjs.org/static/demo/). + +```toml +[params.reveal_hugo] +highlight_theme = "zenburn" +``` + +--- + +## Extending the layout + +Use partials to add HTML to the page for one or all presentations at a time. + + +πŸ’‘ This is the recommended way to add script and style tags to customize your presentations. + + +--- + +Here is where to put partials for different presentations and places in the DOM. +

+ +| Presentation | Before </head> | Before </body> | +|--------------|---------------------------------|---------------------------------| +| All | reveal-hugo/head.html | reveal-hugo/body.html | +| Root | home/reveal-hugo/head.html | home/reveal-hugo/body.html | +| Section | {section}/reveal-hugo/head.html | {section}/reveal-hugo/body.html | + +  + + + +πŸ’‘ You can also create an `end.html` to put content before the end of the `.reveal` div tag. + + + +--- + +## Custom CSS Example + +In `home/reveal-hugo/head.html`: + +```html + +``` + +--- + +## Custom JS Example + +In `home/reveal-hugo/body.html`: + +```html + +``` + +--- + +### Extending the layout +#### (alternative) + +You can declare a custom CSS or javascript in your configuration. + +```toml +[reveal_hugo] +custom_css = "css/custom.css" +custom_js = "js/custom.js" +``` + + + +These files can be located in `static/css`, `static/js` folder + +πŸ’‘ See the [extending layout example](/extending-layout-example/#) for more details. + + diff --git a/content/home/features.md b/content/home/features.md new file mode 100644 index 0000000..5d70186 --- /dev/null +++ b/content/home/features.md @@ -0,0 +1,25 @@ ++++ +weight = 10 ++++ + +## What's included? + +- All Reveal.js HTML, CSS and JS (v3.9.2) +- All out-of-the-box Reveal.js themes +- Two custom Reveal.js themes (including this one) + +
+
+ +[see the code on github](https://github.com/dzello/reveal-hugo) + +--- + +## Features + +- Write slides in Markdown in one or more files +- Shortcodes for fragments, sections, slides & more +- All Reveal.js parameters can be customized +- Any Hugo section can be output as a presentation +- Supports offline development or using a CDN + diff --git a/content/home/resources.md b/content/home/resources.md new file mode 100644 index 0000000..e19cbc1 --- /dev/null +++ b/content/home/resources.md @@ -0,0 +1,43 @@ ++++ +weight = 42 ++++ + +# Resources + +--- + +## Code and docs + +- [reveal-hugo Github README](https://github.com/dzello/reveal-hugo) +- [Content for this presentation](https://github.com/dzello/reveal-hugo/tree/master/exampleSite) + +--- + +## External resources + +- [Reveal.js](https://revealjs.com/) +- [Hugo docs](https://gohugo.io/) +- [Hugo output format docs](https://gohugo.io/templates/output-formats/) + +--- + +## Designed to... + +- Deploy to [Netlify](https://netlify.com/) +- Edit with [Forestry](https://forestry.io/) + +--- + +# πŸ™ + +Contribute by opening issues and pull requests. + +--- + +# Thanks! + +--- + +# ↩️ + +#### [Start over](#) diff --git a/content/home/shortcodes/fragment.md b/content/home/shortcodes/fragment.md new file mode 100644 index 0000000..e53592c --- /dev/null +++ b/content/home/shortcodes/fragment.md @@ -0,0 +1,41 @@ ++++ +weight = 30 ++++ + +## Fragment + +The `fragment` shortcode makes content appear incrementally. + +``` +{{%/* fragment */%}} One {{%/* /fragment */%}} +{{%/* fragment */%}} Two {{%/* /fragment */%}} +{{%/* fragment */%}} Three {{%/* /fragment */%}} +``` + +{{% fragment %}} One {{% /fragment %}} +{{% fragment %}} Two {{% /fragment %}} +{{% fragment %}} Three {{% /fragment %}} + +--- + +## Frag + +The `frag` shortcode is more terse than `fragment`. It accepts a `c` attribute. + +``` +{{}} +{{}} +{{}} +``` + +{{< frag c="One" >}} +{{< frag c="Two" >}} +{{< frag c="Three" >}} + +--- + +Both `fragment` and `frag` accept two additional parameters: + +- `class`: sets the class of the wrapping `span` element +- `index`: controls the order in which sections will appear + diff --git a/content/home/shortcodes/introduction.md b/content/home/shortcodes/introduction.md new file mode 100644 index 0000000..2978a52 --- /dev/null +++ b/content/home/shortcodes/introduction.md @@ -0,0 +1,11 @@ ++++ +weight = 29 ++++ + +# Shortcodes + +--- + +Hugo's shortcodes are similar to functions or templates that extend what you can do with Markdown. + +[Shortcode documentation](https://gohugo.io/content-management/shortcodes/) \ No newline at end of file diff --git a/content/home/shortcodes/markdown.md b/content/home/shortcodes/markdown.md new file mode 100644 index 0000000..0c49b4e --- /dev/null +++ b/content/home/shortcodes/markdown.md @@ -0,0 +1,38 @@ ++++ +weight = 36 ++++ + +{{< markdown >}} + +## Markdown + +Reveal.js has its own [markdown processor](https://github.com/hakimel/reveal.js#markdown). To use that instead of Hugo, surround a slide with the markdown shortcode. + +```markdown +{{}} + +# Hello world! + +{{}} +``` + +
+ +πŸ’‘ Make sure to use the `{{}}` shortcode syntax to avoid rendering by Hugo. + + +--- + + + +Reveal.js markdown uses HTML comments to change slide properties, like background color. + +```markdown +{{}} + +# I'm a colorful slide +{{}} +``` + +{{< /markdown >}} + diff --git a/content/home/shortcodes/other.md b/content/home/shortcodes/other.md new file mode 100644 index 0000000..fda5276 --- /dev/null +++ b/content/home/shortcodes/other.md @@ -0,0 +1,49 @@ ++++ +weight = 38 ++++ + +## Notes + +Add speaker notes (with markdown) to your presentation with the `note` shortcode. Type 's' to see this slide's speaker notes. + +```markdown +--- + +{{%/* note */%}} +- You found the **speaker notes**! +{{%/* /note */%}} + +--- +``` + +{{% note %}} +- You found the **speaker notes**! +{{% /note %}} + +--- + +{{< slide notes="You found the notes!" >}} + +## Notes + +You can also add notes with the `slide` shortcode and `notes` attribute: + +```markdown +--- + +{{%/* slide notes="You found the notes!" */%}} + +--- +``` + +--- + +
+

Write slides in HTML

+

Use a section tag with a data-noprocess attribute to avoid any processing by reveal-hugo.

+ 
+<section data-noprocess>
+  <h1>Hello world!</h1>
+</section>
+ πŸ’‘ This is useful if you can't get Markdown to output exactly what you want. +
diff --git a/content/home/shortcodes/section.md b/content/home/shortcodes/section.md new file mode 100644 index 0000000..797ba21 --- /dev/null +++ b/content/home/shortcodes/section.md @@ -0,0 +1,44 @@ ++++ +weight = 33 ++++ + +{{% section %}} + +## Section + +The `section` shortcode groups slides into a **vertical display**. + +
+ +use the down arrow or swipe down to continue + +
+πŸ”½ + +--- + +Put the shortcode around the slides you want to group together. + +```markdown +{{%/* section */%}} + +## Section slide 1 + +--- + +## Section slide 2 + +{{%/* /section */%}} +``` + +Keep going down. + +--- + +## That's it! + +Use the right arrow or swipe right to continue. + +{{% /section %}} + + diff --git a/content/home/shortcodes/slide.md b/content/home/shortcodes/slide.md new file mode 100644 index 0000000..3ce5b8c --- /dev/null +++ b/content/home/shortcodes/slide.md @@ -0,0 +1,250 @@ ++++ +weight = 34 ++++ + +## Slide + +Use this shortcode when you need to customize slide attributes like id, class, background color and transition. + +--- + +{{< slide class="hello" >}} + +## Slide + +Add the shortcode above the slide's content, below the `---`. + +```markdown +--- + +{{}} + +## Hello, world! + +--- +``` + +--- + +{{< slide transition="zoom" transition-speed="fast" >}} + +## Custom slide 1 + +Did you notice? This slide has a fast zoom transition. + +```markdown +--- + +{{}} + +## Custom slide 1 + +--- +``` + +--- + +{{< slide background-color="#FF4081" >}} + +## Custom slide 2 + +This slide has a different background color. + +```markdown +--- + +{{}} + +## Custom slide 2 + +--- +``` + +--- + +{{< slide background-image="/images/alex-litvin-790876-unsplash.jpg" background-color="#000000" >}} + +## Custom slide 3 + +This slide has a background image. + +```markdown +--- + +{{}} + +--- +``` + +(credit Alex Litvin) + +--- + +{{< slide id="custom-slide" >}} + +πŸ’‘ Tip: Setting a slide's `id` attribute makes it easy to link to from other parts of the presentation. +

+ +```markdown +--- + +{{}} + +## Custom slide + +--- +``` + +--- + +```markdown +[Try the link](#custom-slide) +``` + +
+ +[Try the link](#custom-slide) + +--- + +Slide attribute possibilities from the [Reveal.js docs](https://github.com/hakimel/reveal.js): + +- `autoslide` +- `state` +- `background` +- `background-color` +- `background-image` +- `background-size` +- `background-position` +- `background-repeat` + +--- + +- `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` + +--- + +{{% section %}} + +## Slide templates + +Store sets of common slide attributes in front matter variables and apply them to slides with the template attribute. + +
+ +navigate down to learn more + +
+πŸ”½ + +--- + +Create templates in config.toml, _index.md or the current page's front matter. Put them under the **templates** key with a meaningful name: + +```toml +[reveal_hugo.templates.hotpink] +class = "hotpink" +background = "#FF4081" +``` + +--- + +{{< slide template="hotpink" >}} + +Apply the template using the **template** attribute of the slide shortcode: + +```markdown +{{}} + +# I'm a hot pink slide! +``` + +--- + +If a template exists in multiple configurations, it's properties will be merged. If a property is declared multiple times, the order of precedence is: + +- page +- section (_index.md) +- site (config.toml) + +{{% /section %}} + +--- + +{{% section %}} + +{{< slide content="home.reusable" >}} + +--- + +{{< slide content="common.nested.reusable" >}} + +{{% /section %}} + +--- + +{{% section %}} + +## Slide-specific CSS + +Add more variety to your presentation by applying slide-specific CSS. + +
+ +navigate down to learn more + +
+πŸ”½ + +--- + +First, use the `slide` shortcode to give the slide a class: + +```markdown +--- + +{{}} + +# πŸ“ˆ + +# πŸ“Š + +--- +``` + +--- + +Next, use a layout extension partial like `reveal-hugo/head.html` to add CSS selectors: + +```html + +``` + +--- + +{{< slide class="side-by-side" >}} + +# πŸ“ˆ + +# πŸ“Š + +{{% /section %}} diff --git a/content/home/usage.md b/content/home/usage.md new file mode 100644 index 0000000..a9ebe9d --- /dev/null +++ b/content/home/usage.md @@ -0,0 +1,109 @@ ++++ +weight = 20 ++++ + +# Usage + +--- + +## Prerequisite + +First, add this to your `config.toml`: + +```toml +[outputFormats.Reveal] +baseName = "index" +mediaType = "text/html" +isHTML = true +``` + +--- + +### Presentation at site root + +Create `content/_index.md`: + +```markdown ++++ +outputs = ["Reveal"] ++++ + +# Slide 1 + +Hello world! +``` + +--- + +### Add slides + +Separate them by `---` surrounded by blank lines: + +``` +# Slide 1 + +Hello world! + +--- + +# Slide 2 + +Hello program! +``` + +--- + +### Add slides with other files + +Add slides to `content/home/*.md` + +```markdown ++++ +weight = 10 ++++ + +# Slide 3 + +--- + +# Slide 4 +``` + +πŸ’‘ Tip: Use `weight` to specify the order that files should be considered. + +--- + +### Presentation at '/{section}/' + +Add slides to `content/{section}/_index.md`: + +```markdown ++++ +outputs = ["Reveal"] ++++ + +# Slide 1 + +--- + +# Slide 2 +``` + +--- + +Add slides from other files in `content/{section}/*.md` + +```markdown ++++ +weight = 10 ++++ + +# Slide 3 + +--- + +# Slide 4 +``` + +πŸ’‘ Tip: Use `weight` to specify the order that files should be considered. + diff --git a/content/hugo-hl-example/_index.md b/content/hugo-hl-example/_index.md new file mode 100644 index 0000000..279254c --- /dev/null +++ b/content/hugo-hl-example/_index.md @@ -0,0 +1,113 @@ ++++ +title = "Hugo highlighting example" +outputs = ["Reveal"] + +[reveal_hugo] +theme = "simple" ++++ + +## Hugo Highlighter Presentation + +This is an example of a presentation using Hugo's compile-time syntax highlighter. + +--- + +Reveal.js uses Javascript for syntax highlighting (via Highlight.js). This might slow the presentation down if many slides contain code. + +--- + +Hugo has a built-in [compile-time highlighter](https://gohugo.io/content-management/syntax-highlighting/), and it's lightning fast too! + +--- + +You can enable it using the `highlight` shortcode. + +{{< highlight go >}} +{{}} + +package main + +import "fmt" + +func main() { + fmt.Println("Hello world!") +} + +{{}} +{{< /highlight >}} + +--- + +Several options are supported, check [Hugo's documentation](https://gohugo.io/content-management/syntax-highlighting/). + +{{< highlight go "style=github,linenos=inline,hl_lines=8" >}} +{{}} + +package main + +import "fmt" + +func main() { + fmt.Println("Hello world!") +} + +{{}} +{{< / highlight >}} + +--- + +You can also use Hugo's highlighter in markdown code fences, +by putting this in `config.toml`: + +{{< highlight toml "style=github" >}} + +# use Hugo's hl in markdown (with or without a language tag) +[markup.highlight] +codeFences = true +style = "github" + +{{< /highlight >}} + +(This can only be enabled globally for all presentations.) + +--- + +- Highlight.js is automatically disabled in code blocks highlighted by Hugo. +- The two highlighters can be even mixed. + +{{< highlight go >}} +package main + +import "fmt" + +func main() { + fmt.Println("Hello world!") +} +{{< / highlight >}} + +```go +package main + +import "fmt" + +func main() { + fmt.Println("Hello world!") +} +``` + +--- + +If you don't need highlight.js at all, you can prevent it from loading. + +{{< highlight toml "style=github" >}} + +# This works both in config.toml and a presentation's front +# matter. Default plugins include highlight.js, so disable them +# and load those that we want manually. + +[params.reveal_hugo] +load_default_plugins = false +plugins = [ + "reveal-js/plugin/zoom-js/zoom.js", + "reveal-js/plugin/notes/notes.js", +] diff --git a/content/logo-example/_index.md b/content/logo-example/_index.md new file mode 100644 index 0000000..1a36d6e --- /dev/null +++ b/content/logo-example/_index.md @@ -0,0 +1,90 @@ ++++ +title = "Logo presentation example" +outputs = ["Reveal"] +[logo] +src = "github-logo.png" +[reveal_hugo] +custom_theme = "reveal-hugo/themes/robot-lung.css" +margin = 0.2 ++++ + +## logo-example + +This presentation shows how to add a logo to each slide, like the GitHub one you see above. + +You can generalize the concept to add any additional markup to your presentations. + +--- + +[See the code for this presentation](https://github.com/dzello/reveal-hugo/blob/master/exampleSite/content/logo-example) + +--- + +For a basic setup, in the front matter, add an image to the presentation's directory. + +Then, add a logo section in the front matter: +```toml +[logo] +src = "github-logo.png" +``` +The front matter should end up looking like this: +```toml ++++ +title = "Logo presentation example" +outputs = ["Reveal"] +[logo] +src = "github-logo.png" ++++ +``` + +--- + +If the logo placement doesn't quite match your needs, you may customize it with the following paramaters: + +```toml +[logo] +src = "github-logo.png" # Location of the file displayed. +alt = "" # Alt text. +width = "15%" # Size of the file. +diag = "1%" # How far from the top right should the file be. +top = "1%" # Overrides diag. +right = "1%" # Overrides diag. +``` + + - Instead of absolute (`250px`), relative measurments (`12.5%`) should be used. They work better with different screen sizes. + + - By default, null (`""`) is used as alt text for logos, as otherwise the alt text would unneededly get read by screen readers. + +--- + +πŸ’‘ Tip: to make the logo settings present on every presentation, add the settings to your site's configuration file `config.toml` under `[params.logo]`: + +```toml +[params.logo] +src = "/img/logo.png" +``` +Note that now, the path to the logo file shall be absolute, and should be stored in `static/img/logo.png` instead. + +--- + +Depending on the theme you're using, your styles will be different.
You may also prefer to put your CSS in an external file or your Reveal.js theme. + +For per-presentation override, you may add custom CSS with the ID `#logo` to: +```text +layouts/partials/{section}/reveal-hugo/body.html +``` + +Substitute `{section}` for `home` if you are adding a logo to the presentation at `content/_index.md`. Otherwise, substitute the name of the Hugo section where your presentation lives. + +For a site-wide override, use: +```text +layouts/partials/{section}/reveal-hugo/body.html +``` + +--- + +# πŸ€— + +That's it. + +Happy Hugo-ing! \ No newline at end of file diff --git a/content/logo-example/github-logo.png b/content/logo-example/github-logo.png new file mode 100644 index 0000000..9a6e56c Binary files /dev/null and b/content/logo-example/github-logo.png differ diff --git a/content/plugin-example/_index.md b/content/plugin-example/_index.md new file mode 100644 index 0000000..507eb5a --- /dev/null +++ b/content/plugin-example/_index.md @@ -0,0 +1,83 @@ ++++ +title = "plugin-example" +description = "Shows how a Reveal.js plugin can be added and used" +outputs = ["Reveal"] +[reveal_hugo] +theme = "night" +margin = 0.2 +plugins = ["plugin/gallery/gallery.plugin.js"] ++++ + +# plugin-example + +--- + +This presentation demonstrates how a Reveal.js plugin can be added. + +--- + +The plugin is called [revealjs-simple-gallery](https://github.com/marcins/revealjs-simple-gallery). + +--- + +It can make any slide an image gallery. Here are a few examples. + +--- + +
    +
  • Default settings (Photo by Oscar Fernandez Alonso on Flickr)
    • +
  • Default settings (Photo by bullcitydogs on Flickr)
    • +
  • Default settings (Photo by Lance McCord on Flickr)
    • +
+ +--- + +
    +
  • Infinite iterations, fast transition (Photo by Oscar Fernandez Alonso on Flickr)
    • +
  • Infinite iterations, fast transition (Photo by bullcitydogs on Flickr)
    • +
  • Infinite iterations, fast transition (Photo by Lance McCord on Flickr)
    • +
+ +--- + +
    +
  • Full screen, two iterations, slow transition (Photo by Oscar Fernandez Alonso on Flickr)
    • +
  • Full screen, two iterations, slow transition (Photo by bullcitydogs on Flickr)
    • +
  • Full screen, two iterations, slow transition (Photo by Lance McCord on Flickr)
    • +
+ +--- + +See the [revealjs-simple-gallery GitHub repo](https://github.com/marcins/revealjs-simple-gallery) to learn about more customization options. + +--- + +These were the steps to use this plugin for this reveal-hugo presentation. + +--- + +### 1 + +Copy the plugin CSS and JavaScript into the static directory + +--- + +### 2 + +Add the JavaScript file path to the `plugins` field in the front matter + +--- + +### 3 + +Create a `head.html` partial inside of `layouts/partials/plugin-example/reveal-hugo` + +--- + +### 4 + +In `head.html`, add a stylesheet link tag that loads the plugin CSS + +--- + +## THE END \ No newline at end of file diff --git a/content/plugin-example/sample1.jpg b/content/plugin-example/sample1.jpg new file mode 100644 index 0000000..497d5d1 Binary files /dev/null and b/content/plugin-example/sample1.jpg differ diff --git a/content/plugin-example/sample2.jpg b/content/plugin-example/sample2.jpg new file mode 100644 index 0000000..a62dbdf Binary files /dev/null and b/content/plugin-example/sample2.jpg differ diff --git a/content/plugin-example/sample3.jpg b/content/plugin-example/sample3.jpg new file mode 100644 index 0000000..dad2884 Binary files /dev/null and b/content/plugin-example/sample3.jpg differ diff --git a/content/section-example/_index.md b/content/section-example/_index.md new file mode 100644 index 0000000..5d42bc3 --- /dev/null +++ b/content/section-example/_index.md @@ -0,0 +1,19 @@ ++++ +title = "Section presentation example" +outputs = ["Reveal"] +[reveal_hugo] +theme = "night" +margin = 0.2 ++++ + +# Section Presentation + +This is an example of a section presentation. + +--- + +Section presentations are completely separate from the root presentation and each other. + +--- + +Additional content files can be placed in the section and will be added to the presentation in the order of their weight. \ No newline at end of file diff --git a/content/section-example/presentation.md b/content/section-example/presentation.md new file mode 100644 index 0000000..0309317 --- /dev/null +++ b/content/section-example/presentation.md @@ -0,0 +1,8 @@ ++++ +weight = 10 ++++ + +# Including... + +Content from files like this one. + diff --git a/content/template-example/_index.md b/content/template-example/_index.md new file mode 100644 index 0000000..5b1ec68 --- /dev/null +++ b/content/template-example/_index.md @@ -0,0 +1,45 @@ ++++ +title = "Template presentation" +outputs = ["Reveal"] +[reveal_hugo] +theme = "night" +margin = 0.2 +[reveal_hugo.templates.blue] +background = "#0011DD" +transition = "zoom" ++++ + +## Template Example + +--- + +This presentation shows how to take advantage of reveal-hugo's slide template feature. + +--- + +Slide templates let you specify groups of slide attributes in one place and reuse them throughout the presentation. + +--- + +{{< slide template="blue" >}} + +Here's an example of using a template called `blue`, defined in the front matter of this presentation's `_index.md` file. + +--- + +The template can contain any valid slide customization params: + +```toml +[reveal_hugo.templates.blue] +background = "#0011DD" +transition = "zoom" +``` + +--- + +Then add it to any slide using the slide shortcode: + +``` +{{}} +``` + diff --git a/content/template-example/continued.md b/content/template-example/continued.md new file mode 100644 index 0000000..85ac367 --- /dev/null +++ b/content/template-example/continued.md @@ -0,0 +1,16 @@ ++++ ++++ + +{{< slide template="grey" >}} + +Templates can be specified in `config.toml` as well, for reusability across multiple presentations. + +``` +[params.reveal_hugo.templates.grey] +background = "#424242" +transition = "convex" +``` + +--- + +## THE END \ No newline at end of file diff --git a/data/common/nested.toml b/data/common/nested.toml new file mode 100644 index 0000000..1d5cd59 --- /dev/null +++ b/data/common/nested.toml @@ -0,0 +1,19 @@ +reusable = ''' + +You can organize reusables into folder. + +An an `example` key in `data/common/nested.toml` + +```toml +example = "I'm a slide" +``` +
+ +Set the `content` attribute to "common.nested.example": + +```markdown +{{< slide content="common.nested.example" >}} +``` + +''' + diff --git a/data/home.toml b/data/home.toml new file mode 100644 index 0000000..599fd62 --- /dev/null +++ b/data/home.toml @@ -0,0 +1,46 @@ +# Note: it seems that under goldmark, markdown in data templates has issues. +# In particular "---" is converted to
even inside code fences! + +reusable = ''' + +## Reusable slides + +Store markdown in a [data template](https://gohugo.io/templates/data-templates/) and reuse it in multiple sections or presentations. + +
+ +navigate down to learn more + +
+πŸ”½ + +--- + +Add a `example` key to data/home.toml: + +```toml +example = "I'm a slide" +``` +
+ +Set the `content` attribute to "home.example": + +```markdown +{{< slide content="home.example" >}} +``` + +--- + +πŸ’‘ Each data template entry can contain one or more slides, separated by `---` with newlines. + +--- + +πŸ’‘ All other slide shortcode attributes (background, transition, etc.) can be used and will be applied to each slide in the data template entry. + +--- + +πŸ’‘ Adding a new file in `data` folder requires to restart `hugo` + +πŸ’‘ Symbolic links are not allowed in `data` folder + +''' diff --git a/layouts/_default/baseof.reveal.html b/layouts/_default/baseof.reveal.html new file mode 100644 index 0000000..61b735f --- /dev/null +++ b/layouts/_default/baseof.reveal.html @@ -0,0 +1,47 @@ + + + + {{ partial "layout/head" . }} + {{ partial "layout/theme" . }} + + {{- partial "reveal-hugo/head" . -}} + + {{- $sectionHeadPartial := printf "%s/reveal-hugo/head" (.Page.Section | default "home") -}} + {{- if fileExists (printf "layouts/partials/%s.html" $sectionHeadPartial) -}}{{ partial $sectionHeadPartial . }}{{- end }} + + + {{ if .Param "logo.src" }} + + + {{ end }} +
+
+ {{- block "main" . -}}{{- end -}} +
+ + {{- partial "reveal-hugo/end" . -}} + + {{- $sectionHeadPartial := printf "%s/reveal-hugo/end" (.Page.Section | default "home") -}} + {{- if fileExists (printf "layouts/partials/%s.html" $sectionHeadPartial) -}}{{ partial $sectionHeadPartial . }}{{- end }} +
+ {{- partial "layout/javascript" . }} + + {{- partial "reveal-hugo/body" . }} + + {{- $sectionBodyPartial := printf "%s/reveal-hugo/body" (.Page.Section | default "home") -}} + {{- if fileExists (printf "layouts/partials/%s.html" $sectionBodyPartial) -}}{{ partial $sectionBodyPartial . }}{{- end }} + + diff --git a/layouts/_default/bundle.reveal.html b/layouts/_default/bundle.reveal.html new file mode 100644 index 0000000..62fb5c8 --- /dev/null +++ b/layouts/_default/bundle.reveal.html @@ -0,0 +1,4 @@ +{{ define "main" }} + {{ partial "reveal-hugo/slides" (slice .Page) }} + {{ partial "reveal-hugo/slides" (.Resources.ByType "page") }} +{{ end }} diff --git a/layouts/_default/index.reveal.html b/layouts/_default/index.reveal.html new file mode 100644 index 0000000..1b4b67c --- /dev/null +++ b/layouts/_default/index.reveal.html @@ -0,0 +1,4 @@ +{{ define "main" }} + {{ partial "reveal-hugo/slides" (slice .Page) }} + {{ partial "reveal-hugo/slides" (where .Site.RegularPages "Type" "home") }} +{{ end }} diff --git a/layouts/_default/list.reveal.html b/layouts/_default/list.reveal.html new file mode 100644 index 0000000..63e4b9d --- /dev/null +++ b/layouts/_default/list.reveal.html @@ -0,0 +1,4 @@ +{{ define "main" }} + {{ partial "reveal-hugo/slides" (slice .Page) }} + {{ partial "reveal-hugo/slides" (where .Pages "Kind" "page") }} +{{ end }} diff --git a/layouts/_default/single.reveal.html b/layouts/_default/single.reveal.html new file mode 100644 index 0000000..e69de29 diff --git a/layouts/partials/highlightjs-linenumbers-example/reveal-hugo/body.html b/layouts/partials/highlightjs-linenumbers-example/reveal-hugo/body.html new file mode 100644 index 0000000..64a94d9 --- /dev/null +++ b/layouts/partials/highlightjs-linenumbers-example/reveal-hugo/body.html @@ -0,0 +1,6 @@ + + \ No newline at end of file diff --git a/layouts/partials/home/reveal-hugo/body.html b/layouts/partials/home/reveal-hugo/body.html new file mode 100644 index 0000000..1dba7f9 --- /dev/null +++ b/layouts/partials/home/reveal-hugo/body.html @@ -0,0 +1,9 @@ + + + + diff --git a/layouts/partials/home/reveal-hugo/end.html b/layouts/partials/home/reveal-hugo/end.html new file mode 100644 index 0000000..39d6fcd --- /dev/null +++ b/layouts/partials/home/reveal-hugo/end.html @@ -0,0 +1,4 @@ +
+
+
+
diff --git a/layouts/partials/home/reveal-hugo/head.html b/layouts/partials/home/reveal-hugo/head.html new file mode 100644 index 0000000..c99b743 --- /dev/null +++ b/layouts/partials/home/reveal-hugo/head.html @@ -0,0 +1,39 @@ + + + diff --git a/layouts/partials/layout/head.html b/layouts/partials/layout/head.html new file mode 100644 index 0000000..085923a --- /dev/null +++ b/layouts/partials/layout/head.html @@ -0,0 +1,7 @@ + +{{ or .Page.Title .Site.Title }} +{{ with $.Param "description" }}{{ end }} +{{ with .Site.Author.name }}{{ end }} + + + \ No newline at end of file diff --git a/layouts/partials/layout/javascript.html b/layouts/partials/layout/javascript.html new file mode 100644 index 0000000..fe99cb9 --- /dev/null +++ b/layouts/partials/layout/javascript.html @@ -0,0 +1,63 @@ + + + + +{{- $reveal_location := $.Param "reveal_hugo.reveal_cdn" | default "reveal-js" -}} + + + + + + + + + + +{{ if $.Param "reveal_hugo.load_default_plugins" | default true }} + {{ $default_plugins := slice "plugin/markdown/marked.js" "plugin/markdown/markdown.js" "plugin/highlight/highlight.js" "plugin/zoom-js/zoom.js" }} + {{ range $default_plugins }} + + {{ end }} + + +{{ end }} + +{{ range $.Param "reveal_hugo.plugins" }} + +{{ end }} +{{- $custom_js := $.Param "reveal_hugo.custom_js" -}} +{{- if $custom_js -}} + +{{- end -}} diff --git a/layouts/partials/layout/theme.html b/layouts/partials/layout/theme.html new file mode 100644 index 0000000..a4f7c86 --- /dev/null +++ b/layouts/partials/layout/theme.html @@ -0,0 +1,28 @@ + +{{- $reveal_location := $.Param "reveal_hugo.reveal_cdn" | default "reveal-js" -}} +{{- $highlight_location := $.Param "reveal_hugo.highlight_cdn" | default "highlight-js" -}} +{{- $custom_theme := $.Param "reveal_hugo.custom_theme" -}} + + +{{- $custom_theme := $.Param "reveal_hugo.custom_theme" -}} +{{- if $custom_theme -}} + {{- $custom_theme_options := $.Param "reveal_hugo.custom_theme_options" | default dict -}} + {{- if $.Param "reveal_hugo.custom_theme_compile" -}} + {{ $asset := resources.Get $custom_theme | resources.ExecuteAsTemplate "_.scss" . | toCSS $custom_theme_options | minify | fingerprint }} + + {{- else -}} + + {{- end -}} +{{ else -}} + {{- $theme := $.Param "reveal_hugo.theme" | default "black" -}} + +{{ end -}} +{{ if $.Param "reveal_hugo.load_default_plugins" | default true -}} + + {{- $highlight_theme := $.Param "reveal_hugo.highlight_theme" | default "default" -}} + +{{- end }} +{{- $custom_css := $.Param "reveal_hugo.custom_css" -}} +{{- if $custom_css -}} + +{{- end -}} diff --git a/layouts/partials/logo-example/reveal-hugo/body.html b/layouts/partials/logo-example/reveal-hugo/body.html new file mode 100644 index 0000000..b54ef2f --- /dev/null +++ b/layouts/partials/logo-example/reveal-hugo/body.html @@ -0,0 +1,9 @@ + + \ No newline at end of file diff --git a/layouts/partials/plugin-example/reveal-hugo/head.html b/layouts/partials/plugin-example/reveal-hugo/head.html new file mode 100644 index 0000000..7c4c42d --- /dev/null +++ b/layouts/partials/plugin-example/reveal-hugo/head.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/layouts/partials/reveal-hugo/body.html b/layouts/partials/reveal-hugo/body.html new file mode 100644 index 0000000..f2dd4bf --- /dev/null +++ b/layouts/partials/reveal-hugo/body.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/layouts/partials/reveal-hugo/end.html b/layouts/partials/reveal-hugo/end.html new file mode 100644 index 0000000..1ca9f46 --- /dev/null +++ b/layouts/partials/reveal-hugo/end.html @@ -0,0 +1 @@ + diff --git a/layouts/partials/reveal-hugo/head.html b/layouts/partials/reveal-hugo/head.html new file mode 100644 index 0000000..ed1e892 --- /dev/null +++ b/layouts/partials/reveal-hugo/head.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/layouts/partials/reveal-hugo/slides.html b/layouts/partials/reveal-hugo/slides.html new file mode 100644 index 0000000..0bed8a9 --- /dev/null +++ b/layouts/partials/reveal-hugo/slides.html @@ -0,0 +1,26 @@ + +{{ range . -}} + + {{- if ne (len .Content) 0 -}} + + {{- $content := replace .Content "
\n\n
" "
" -}} + + + {{- $content := replaceRE ` + {{- $content := replaceRE `()` `$1" data-line-numbers>` $content -}} + + {{- $content := replaceRE `()` `$1" data-line-numbers="$2">` $content -}} + + {{- $content := replace $content "
" "
" -}} + + {{- range (split $content "
") -}} + + {{- if not (in . "data-noprocess") -}} +
+ {{- end -}} + {{- . | safeHTML -}} +
+ {{- end -}} + {{- end -}} +{{- end }} diff --git a/layouts/shortcodes/frag.html b/layouts/shortcodes/frag.html new file mode 100644 index 0000000..c1de8c8 --- /dev/null +++ b/layouts/shortcodes/frag.html @@ -0,0 +1,4 @@ + + {{ .Get "c" }} + \ No newline at end of file diff --git a/layouts/shortcodes/fragment.html b/layouts/shortcodes/fragment.html new file mode 100644 index 0000000..ecdebfb --- /dev/null +++ b/layouts/shortcodes/fragment.html @@ -0,0 +1,4 @@ +{{/* Render .Inner before processing the shortcode. */}} +{{ $_hugo_config := `{ "version": 1 }` }} +{{ .Inner }} + diff --git a/layouts/shortcodes/markdown.html b/layouts/shortcodes/markdown.html new file mode 100644 index 0000000..f5effbc --- /dev/null +++ b/layouts/shortcodes/markdown.html @@ -0,0 +1,8 @@ +
+ +
\ No newline at end of file diff --git a/layouts/shortcodes/note.html b/layouts/shortcodes/note.html new file mode 100644 index 0000000..f5ee55e --- /dev/null +++ b/layouts/shortcodes/note.html @@ -0,0 +1,4 @@ +{{/* Markdown is not rendered inside