grunt-presentation-builder

Create HTML presentations from multiple slide files, uses presentation-builder

Getting Started

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-presentation-builder --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-presentation-builder');

Features

• Support for nested slides (Framework dependant)
• Writing slides using markdown (uses markdown-it)
• Sections in markdown files which can be positioned in different parts of a layout
• Usage of grunt templates in the layouts/index.html file (only with <%= %> currently)
• Slide files with front matter (uses front-matter)
• Usage of layout files to avoid writing the layout as part of the markdown

pbuilder Task

Run this task with the grunt pbuilder command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide. The files passed to the tasks are the slides for the presentation.

Options

layoutAttributes

Type: Object

The properties defined for this object will be available for usage in the defined layouts and the index file. If a file's front matter defines a property with the same name, then the front matter property will have precedence.

slides

Type: Array<String> | Array<Object>

An array containing the file names for the slides without the extension. The array is used to define the order in which the slides should be shown in the presentation. You can pass an object with a slides property to create nested slides. Currently only one level of nesting is supported.

outputDir

Type: String

The directory in which the built presentation is created.

index

Type: String

An index.html file containing any markup, scripts, stylesheets needed by the presentation framework you use. In order to have the created slides added to the index file, use <%= slides %> at the position you want the slides to be rendered.

layouts

Type: Array<String>

An array of layout files. Supports globbing patterns. The way layout files are written is framework specific.

nestedSlidePrefix

Type: String

HTML tag to be used as a wrapper for nested slides. Default is <section> which works for reveal.js.

nestedSlideSuffix

Type: String

Closing tag for the nestedSlidePrefix option. Default is </section>.

sectionSplitter

Type: RegExp

Regular expression used to detect sections in the slide files. Default is /---(.*)---/g.

slideResolutionFullPath

Type: Boolean

Changes the way slides given in the slides option are matched to slides read in the files property. Default is false. See presentation-builder for more information.

markdownRendererOptions

Type: Object

Options to configure the markdown renderer. See markdown-it for possible options. Note that default is used as preset and this cannot be changed.

Usage example

pbuilder: {
  targetName: {
    options: {
      layoutAttributes: {
        title: 'Layouts', // Title in index.html head
        footer: 'Copyright....' // footer for all slides
      },
      slides: [
        'slide1',
        'slide2',
        slides: [ // nested slides
          'slide3',
          'slide4'
        ]
      ],
      index: './index.html',
      outputDir: 'build/',
      layouts: ['./layouts/*.html', './some/other/layout.html'],
      sectionSplitter: /---(.*)---/g,
      nestedSlidePrefix: '<section>',
      nestedSlideSuffix: '</section>'
    },
    files: [{
      expand: true,
      cwd: './slides/',
      src: ['*.md']
    }]
  }
}

You can check out the demos for more comprehensive examples on how to use the builder.

Demos

• pbuilder with reveal.js

If you have a demo using grunt-presentation-builder, then open a pull request to add a link to your demo or just open an issue with the link.

Slide files

A slide (markdown file) can have a front matter and one or more sections. Example slide file:

---
title: Slide title
layout: layout_name
---

---section1---
Contents for the first section

---section2---
Contents for the second section

The 4 first lines of the file define the front matter. Any attribute defined there can later be used in a layout. For example in order to reference the title use: <%= title %>. Attributes in the front matter override attributes with the same name defined in the layoutAttributes options property.

The names between the dashes define sections. For example the first section can be referenced as such: <%= sections.section1 %>. In case a file defines no sections then you can use <%= sections.content %> to get the contents of the file in the template. Each section gets through a markdown parser (markdown-it) before it is given to the template.

There is a special section with name code_editor which does not get parsed. The contents of that section are given to the template as is and it is meant to be used for a code editor in the slide. You can have a look at the code_demo presentation in the pbuilder with reveal.js to see how it is used.

License

MIT License