generator-bespoke

Bespoke.js Presentation Generator

A Yeoman generator that scaffolds a Bespoke.js presentation project.

Features

The boilerplate project this generator creates includes a Gulp build system, a preview server with LiveReload, and a GitHub Pages deployment task. The project is also setup to perform Stylus compilation and, optionally, Pug (formerly Jade) or AsciiDoc conversion to HTML, depending on the templating engine you chose.

The following Bespoke.js plugins are always included by default:

• bespoke-classes
• bespoke-nav
• bespoke-scale
• bespoke-fullscreen
• bespoke-overview
• bespoke-bullets
• bespoke-hash
• bespoke-extern

Based on your responses to the prompts in the generator, your presentation may also include the following optional plugins:

• bespoke-prism
• bespoke-multimedia

Prerequisites

In order to use this generator and the project it creates, you must satisify the following prerequisites:

• Node.js >= 16
  • We strongly recommend using nvm to manage your Node.js installation.
• Yeoman

  $ npm i -g yo

Usage

Once you have satisfied the prerequisites, install the generator-bespoke package globally:

$ npm i -g generator-bespoke

You can verify the generator installed properly, and view its usage statement, by running:

$ yo bespoke --help

The generator must be run from inside a project folder. Therefore, to start, create a new directory for the project and switch to it:

$ mkdir presentation-hello-world
$ cd presentation-hello-world

Another approach is to first create an empty repository on GitHub, then clone and switch to it:

$ git clone [e-mail]:<username>/presentation-hello-world.git
$ cd presentation-hello-world

The benefit of the clone workflow is that the generator will automatically populate the repository field in the generated package.json file.

IMPORTANT If you plan to create an AsciiDoc-based presentation, be ready for the generator to execute the bundle command. This command installs the Asciidoctor Bespoke gem and its dependencies. The gems are installed to the local .bundle/gems directory.

If you use RVM to manage Ruby, switch to your preferred Ruby version using rvm use (e.g., rvm use 3.2) before running the next command. You may also choose to declare your preferred Ruby version in the file named .ruby-version at the root of the project.

If you use a different Ruby selector, make sure your Ruby environment is prepared to run bundle.

To disable this behavior, you can use the --skip-install switch.

Scaffold a new presentation using:

$ yo bespoke

If you want the generator to skip npm i (and also bundle for an AsciiDoc-based presentation), use the skip-install switch:

$ yo bespoke --skip-install

In this case, you'll be instructed to execute the the commands that the generator skipped.

Refer to the README at the root of the generated project for instructions on how to get started developing your new presentation.

Presentation Workflow

All source files for the presentation reside in the src directory.

Build the presentation and start a local preview server using:

$ npx gulp serve

Once the server is running, you can view the slides by navigating to http://localhost:8080 in your browser. The build will continue monitoring for changes, so you can work on the presentation and preview it in real time.

Build the presentation without starting the local preview server using:

$ npx gulp

The files are built into the dist directory. You can view the slides by navigating to dist/index.html in your browser.

Compile and publish to GitHub Pages, assuming a git repo with origin pointing to GitHub, using:

$ npx gulp publish

Generator Tests

Tests require Node.js >= 16. Everything created by those tests (files and directories) is located in the user's temporary folder.

First, clone the git repository and switch to the project:

$ git clone [e-mail]:bespokejs/generator-bespoke.git
$ cd generator-bespoke

If you're using nvm to manage your Node.js installation, switch to at least Node.js 4.4.

nvm use 16

Next, install the development dependencies into the project:

$ npm i

Finally, run the tests using:

npm t

The tests verify basic behaviour about the plugin, including:

• Checks that yo bespoke generates correct files for different templating options (Pug, AsciiDoc, HTML)
• Checks that after a yo bespoke, npx gulp serve provides a local server with a working Bespoke.js slide deck
• Checks that after a yo bespoke, npx gulp build generates correct files

License

MIT License