Add shortcodes to the README

README.md

@@ -4,7 +4,7 @@ A Hugo theme for [Reveal.js](https://revealjs.com/) that makes authoring and cus
 
 ![screenshot of reveal-hugo](https://github.com/dzello/reveal-hugo/blob/master/images/screenshot.png?raw=true)
 
-### Example
+## Example
 
 Using reveal-hugo, presentations with multiple slides can be created with just one markdown file, like so:
 
@@ -116,21 +116,148 @@ The Usage guide is contained in the example presentation that lives in this repo
 
 ### Root vs. section presentations
 
-Here's what the folder structure would look like with one root presentation and one section presentation. I use "chunk" in the following example to avoid a collision with Hugo's "section".
+Here's what the folder structure would look like with one root presentation and one section presentation.
 
 ```
 - content
-  - home # special hugo section for adding to the root presentation
+  - home # special section for appending to root presentation
-    - body.md # a chunk of the root presentation
+    - body.md # appends to the root presentation
-    - conclusion.md # another chunk of 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 # a chunk of the ted talk presentation
+    - body.md # appends to the ted talk presentation
-    - conclusion.md # another chunk of 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 of the chunks can be controlled by the `weight` parameter specified in the front matter. The `_index.md` chunk will always come first, though you don't have to put any slides in it if you want to. The Reveal outputFormat need only be added to the `_index.md` file.
+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 Reveal.js attributes for each slide - things like transition, background color and [much more](https://github.com/hakimel/reveal.js/#slide-attributes).
+
+```markdown
+{{% slide background="#FFF" transition="zoom" transition-speed="fast" %}}
+
+# Hello, world!
+
+{{% /slide %}}
+```
+
+#### 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 %}}
+```
+
+### 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
 
@@ -158,10 +285,12 @@ Or in the front matter of an `_index.md` file:
 theme = "moon"
 ```
 
-## Adding HTML to the page
+## Adding HTML to the layout
 
 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 partials 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.
 
+## 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:
@@ -188,21 +317,22 @@ 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.
 
-# Reveal.js favorites
+## Reveal.js tips
 
-Not directly related to reveal-hugo, but these are some of my favorite Reveal.js features and shortcuts.
+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 of my favorite Reveal.js-related tools:
+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).
 
-# Contributing
+## Contributing
 
 Contributions are very welcome. To run the example site in this repository locally, clone this repository and run: