Add more customization

README.md

@@ -1,16 +1,18 @@
 # reveal-hugo
 
-A Hugo theme for [Reveal.js](https://revealjs.com/) that allows you to have multiple slides per markdown file. With it, you can turn any of your Hugo content into a presentation by adding `Reveal` to its output formats.
+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](/images/screenshot.png)
 
-The motivation behind creating this theme is pretty simple - I didn't want to have to manage one markdown file for every slide, which would add the overhead of coming up with a file name, setting a `weight` param in the front matter to keep it in order, etc, all for just a few lines of text. Instead, I like to organize groups of slides into a smaller number of markdown files, each representing a section of the presentation.
-
 ### Example
 
-Using reveal-hugo, a three-slide (or n-slide) presentation can be created with just one markdown file, like so:
+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.
 
@@ -25,13 +27,15 @@ Salu.
 Hola.
 ```
 
-The only requirement is to demarcate slides with `---` surrounded by newlines.
+Just use `---` to split content into different slides.
 
 ## Demo
 
-Visit [https://dzello.com/reveal-hugo/](https://dzello.com/reveal-hugo/) to see a presentation created with this theme. You can also check out this exact repository [deployed to Netlify](https://reveal-hugo.netlify.com/).
+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.
 
-## Usage
+## 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
 
@@ -102,37 +106,35 @@ This is my first slide.
 This is my second slide.
 ```
 
-### Create a root presentation
+## Usage
 
-To create a presentation that lives at the site root, create a `content/_index.md` file and specify that the `Reveal` output format should be used in the front matter:
+The Usage guide is contained in the example presentation that lives in this repository at `exampleSite`. You can access a live version at [https://dzello.com/reveal-hugo/](https://dzello.com/reveal-hugo/).
 
-```toml
+## Configuration
-outputs = ["Reveal"]
+
+Customize the Reveal.js presentation by setting these values in `config.toml` or the front matter of any presentation's `index.md`.
+
+- `params.reveal_hugo.theme`: The Reveal.js theme used, defaults to "black"
+
+Include any other attributes in `params.reveal_hugo` that you'd like to be fed as arguments to `Reveal.initialize`. See the [extensive list of options](https://github.com/hakimel/reveal.js/#configuration) here. Defaults used by this theme are located in `data/reveal_hugo.toml`.
+
+If you're new to TOML, this is how it should look in your `config.toml`:
+
+```TOML
+[params.reveal_hugo]
+theme = "moon"
 ```
 
-Content for this presentation can come from `_index.md`, files in the `home` directory, or any content file whose type is set to `home` in the front matter.
+Or in the front matter of an `_index.md` file:
 
-Use the `weight` param in the front matter to specify the order that content from these files should appear in the presentation, knowing that content from `_index.md` will always come first.
+```TOML
-
+[reveal_hugo]
-```toml
+theme = "moon"
-weight = 20
 ```
 
-### Create a section presentation
+## Injecting HTML
 
-To create a presentation for the content of any section of your Hugo site, just add `Reveal` to its list of `outputFormats` in the front matter of `section/_index.md`:
+If you need to add something to the HTML page, just override the empty partial that lives at `layouts/partials/reveal-hugo/body.html`. This partial is injected into the page just before the closing of the body tag. Common uses would be to add custom CSS or JS to the page.
-
-```toml
-outputs = ["Reveal"]
-```
-
-Section presentations will include content from each file in that section. Again, use the `weight` param to order the sections, knowing that any content in `_index.md` will come first.
-
-Presentations can use a different Reveal.js theme by specifying the `reveal_theme` parameter in the front matter of the section's `_index.md` file.
-
-```toml
-reveal_theme = "moon"
-```
 
 ### Add a Reveal.js presentation to an existing Hugo site
 
@@ -142,11 +144,13 @@ If your Hugo site already has a theme but you'd like to create a presentation fr
 $ cd my-hugo-site
 $ git clone git@github.com:dzello/reveal-hugo.git themes/reveal-hugo
 $ cp -r themes/reveal-hugo/static/reveal static/reveal
-$ cp themes/reveal-hugo/layouts/_default/*.reveal.html layouts/_default
+$ cp -r themes/reveal-hugo/static/reveal_hugo static/reveal_hugo
-$ cp themes/reveal-hugo/layouts/shortcodes/* layouts/shortcodes
+$ cp themes/reveal-hugo/layouts/* layouts
-$ cp themes/reveal-hugo/layouts/partials/* layouts/partials
+$ cp themes/reveal-hugo/data/* data
 ```
 
+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
@@ -160,44 +164,9 @@ Now you can add `outputs = ["Reveal"]` to the front matter of any section's `_in
 
 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.
 
-## Features
-
-### Fragments
-
-Fragments are a Reveal.js concept that lets you introduce content into each slide incrementally. Borrowing the idea from [hugo-theme-revealjs](https://github.com/RealOrangeOne/hugo-theme-revealjs) (thanks!), you can use a `fragment` shortcode to accomplish this in reveal-hugo in the same way.
-
-```markdown
-# Let's count to three...
-{{% fragment %}} One {{% /fragment %}}
-{{% fragment %}} Two {{% /fragment %}}
-{{% fragment %}} Three {{% /fragment %}}
-```
-
-### Sections
-
-Add sections of vertical slides to your presentation by surrounding the relevant slides with the `section` shortcode.
-
-```markdown
-{{% section %}}
-
-# Section slide 1
-
----
-
-# Section slide 2
-
-{{% /section %}}
-```
-
-### Configuration params
-
-These settings go in `config.toml`:
-
-- `params.reveal_theme`: The Reveal.js theme used, defaults to "black"
-
 # Contributing
 
-Contributions are very welcome. To run the example site in this respository locally, clone this repository and run:
+Contributions are very welcome. To run the example site in this repository locally, clone this repository and run:
 
 ```shell
 hugo server -s exampleSite -d ../public --themesDir '../' --theme '.'

data/reveal_hugo.toml

@@ -0,0 +1,6 @@
+[defaults]
+controls = true
+progress = true
+history = true
+center = true
+transition = 'slide' # none/fade/slide/convex/concave/zoom

exampleSite/config.toml

@@ -8,7 +8,9 @@ name = "Josh Dzielak"
 
 [params]
 description = "A description of this presentation"
-reveal_theme = "solarized"
+
+[params.reveal_hugo]
+theme = "solarized"
 
 [outputFormats.Reveal]
 baseName = "index"

exampleSite/content/example/_index.md

@@ -1,7 +1,8 @@
 +++
 title = "Example of a section presentation"
 outputs = ["Reveal"]
-reveal_theme = "moon"
+[reveal_hugo]
+theme = "moon"
 +++
 
 # Section Presentation

layouts/_default/baseof.reveal.html

@@ -9,7 +9,7 @@
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
     <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
     <link rel="stylesheet" href="{{ "reveal/css/reveal.css" | relURL }}">
-    {{ $theme := or .Page.Params.reveal_theme .Site.Params.reveal_theme "black" }}
+    {{ $theme := or .Page.Params.reveal_hugo.theme .Site.Params.reveal_hugo.theme "black" }}
     <link rel="stylesheet" href="{{ printf "reveal/css/theme/%s.css" $theme | relURL }}" id="theme">
     <!-- Theme used for syntax highlighting of code -->
     <link rel="stylesheet" href="{{ "reveal/lib/css/zenburn.css" | relURL }}">
@@ -27,18 +27,10 @@
   </head>
   <body>
     {{ block "main" . }}{{ end }}
-    {{ partial "reveal-hugo/body" . }}
+    <script type="application/json" id="reveal-hugo-params">{{ jsonify .Site.Params.reveal_hugo | safeJS }}</script>
-    <script src="{{ "reveal/lib/js/head.min.js" | relURL }}"></script>
+    <script type="application/json" id="reveal-hugo-defaults">{{ jsonify .Site.Data.reveal_hugo.defaults | safeJS }}</script>
-    <script src="{{ "reveal/js/reveal.js" | relURL }}"></script>
+    <script type="text/javascript">
-    <script>
+      window.revealDependencies = {
-      // More info https://github.com/hakimel/reveal.js#configuration
-      Reveal.initialize({
-        controls: true,
-        progress: true,
-        history: true,
-        center: true,
-        transition: 'slide', // none/fade/slide/convex/concave/zoom
-        // More info https://github.com/hakimel/reveal.js#dependencies
         dependencies: [
           { src: '{{ "reveal/lib/js/classList.js" | relURL }}', condition: function() { return !document.body.classList; } },
           { src: '{{ "reveal/plugin/markdown/marked.js" | relURL }}', condition: function() { return !!document.querySelector( '[data-markdown]' ); } },
@@ -47,8 +39,11 @@
           { src: '{{ "reveal/plugin/search/search.js" | relURL }}', async: true },
           { src: '{{ "reveal/plugin/zoom-js/zoom.js" | relURL }}', async: true },
           { src: '{{ "reveal/plugin/notes/notes.js" | relURL }}', async: true }
-        ]
+      ]};
-      });
     </script>
+    <script src="{{ "reveal/lib/js/head.min.js" | relURL }}"></script>
+    <script src="{{ "reveal/js/reveal.js" | relURL }}"></script>
+    <script src="{{ "reveal-hugo/index.js" | relURL }}"></script>
+    {{ partial "reveal-hugo/body" . }}
   </body>
 </html>

layouts/partials/reveal-hugo/body.html

@@ -1 +1 @@
-<!-- override this partial to add content after the slides -->
+<!-- override this partial to add content before the body closing -->

static/reveal-hugo/index.js

@@ -0,0 +1,6 @@
+// pattern inspired by https://github.com/RealOrangeOne/hugo-theme-revealjs
+var revealParams = JSON.parse(document.getElementById('reveal-hugo-params').innerHTML);
+var revealDefaults = JSON.parse(document.getElementById('reveal-hugo-defaults').innerHTML);
+
+// More info https://github.com/hakimel/reveal.js#configuration
+Reveal.initialize(Object.assign(revealDefaults, revealParams, revealDependencies));