Skip to content
This repository has been archived by the owner on Dec 14, 2018. It is now read-only.

Latest commit

 

History

History
416 lines (309 loc) · 12.6 KB

README.md

File metadata and controls

416 lines (309 loc) · 12.6 KB
Raw

Bespoke.js Deck Skeleton

Make New GitHub release GitHub license David David Travis

wercker status

Description

Bootstrap a new Bespoke.js deck in less than a minute.

Check out the live demo and its source code!

Create your new deck now!

Quick Usage Notes

After the initial bootstrapping steps, jump down to Quickstart and beyond to get up and running.

The only file you are required to edit is where you add your slides: app/partials/slides.static.hbs. Try adding a few <section> elements and watch your slides magically appear! This is a Handlebars template which supports YAML front matter and partials.

Add images or other assets anywhere under app/assets and refer to them with, e.g., if you have app/assets/images/kitty.png, write src="/images/kitten.png".

This skeleton only comes with one plugins and one theme: bespoke-keys and bespoke-theme-cube. Install more with npm install --save (or uninstall existing ones with npm uninstall --save), then load them in app/modules/deck.js.

Since most decks are hosted as part of a larger website, the following typical boilerplate files are not Included: 404.html, crossdomain.xml, and robots.txt.

Features

Bootstrapping a New Project

  1. Clone the master branch of this repository with

    $ git clone --single-branch https://github.com/makenew/deck-bespoke.js.git new-deck-bespoke.js
$ cd new-deck-bespoke.js

    Optionally, reset to the latest release with

    $ git reset --hard deck-bespoke.js-v1.6.3

  2. Run

    $ ./makenew.sh

    and follow the prompts. This will replace the boilerplate, delete itself, and stage changes for commit. This script assumes the project repository will be hosted on GitHub. For an alternative location, you must update the URLs manually.

  3. Fill in the README Description section.

  4. If choosing a license other than the one provided: update LICENSE.txt, the README License section, license badge, and package.json with your chosen license.

  5. Add your own favicons from Favic-o-matic to app/assets/favicon and overwrite app/assets/favicon.ico. You can make a quick Font Awesome favicon at FA2PNG.

  6. Further customize the meta data in app/index.static.hbs and replace app/assets/image.png with a custom image.

  7. Lock your dependencies with npm-shrinkwrap.json. Optionally, lock the Node.js version with .nvmrc and in wercker.yml.

  8. Configure deployment to GitHub pages from wercker and update the wercker badge.

Updating

If you want to pull in future updates from this skeleton, you can fetch and merge in changes from this repository.

If this repository is already set as origin, rename it to upstream with

$ git remote rename origin upstream

and then configure your origin branch as normal.

Otherwise, add this as a new remote with

$ git remote add upstream https://github.com/makenew/deck-bespoke.js.git

You can then fetch and merge changes with

$ git fetch upstream
$ git merge upstream/master

Changelog

Note that CHANGELOG.md is just a template for this skeleton. The actual changes for this project are documented in the commit history and summarized under Releases.

Quickstart

$ git clone https://github.com/makenew/deck-bespoke.js.git
$ cd deck-bespoke.js
$ npm install
$ npm start

Building and Development

Source Code

The makenew-deck-bespoke.js source is hosted on GitHub. Clone the project with

$ git clone https://github.com/makenew/deck-bespoke.js.git

Requirements

You will need Node.js with npm.

Install the development dependencies with

$ npm install

Updating requirements

Requirements are version-locked to ensure consistent deploys.

To use the newest allowed Node packages, or after updating any package versions in package.json, update and stage npm-shrinkwrap.json with

$ npm update
$ npm shrinkwrap --dev
$ git add npm-shrinkwrap.json

Tasks

Primary development tasks are defined under scripts in package.json and available via npm run-script. View them with

$ npm run

Production Build

Lint, test, generate, and optimize the production build to public with

$ npm run dist

The base URL and asset prefix is set at build time in brunch-config.js and gulpfile.js and may be overridden by BASEURL and ASSET_PREFIX.

Deploy to GitHub Pages

Build and deploy to GitHub Pages with

$ npm run deploy

The following environment variables can be set to customize the deploy: DEPLOY_REPO, DEPLOY_BRANCH, DEPLOY_NAME, and DEPLOY_EMAIL.

Deploy from wrecker

Create a new wercker SSH key with the name DEPLOY, add it to a new wercker deploy step, and add it to the GitHub repository as a deploy key with write access.

Brunch

Brunch is responsible for the development cycle and the production build.

Start a local Brunch development server with

$ npm start

If installed globally, brunch may be invoked directly. View available commands with

$ brunch

gulp

Linting, deployment, and optimization is handled by gulp.

In a separate window, use gulp to watch for changes and lint HTML, JavaScript, and Sass files with

$ npm run watch

If installed globally, gulp may be invoked directly. View available commands with

$ gulp --tasks

Tips for Deck Makers

Bespoke.js

The Bespoke.js GitHub page covers how to make a deck.

Put slides in app/partials/slides.static.hbs, e.g.,

<section>Slide 1</section>
<section>Slide 2</section>
<section>Slide 3</section>

Plugins, Themes, and Libraries

  • Install plugins, themes, and any other front end dependencies, e.g., JavaScript modules, Sass libraries, fonts, etc., with npm i --save.
  • Use JavaScript modules directly with import.
  • Bespoke.js is configured in app/modules/deck.js.
  • The node_modules directory exists in the Sass include path via the setting in brunch-config.coffee.
  • Use app/styles/main.scss as the entry point for your styles.
  • All other assets may be placed under app/assets.

Meta Data

Meta data is defined in app/index.static.hbs.

  • Nil values are indicated by a ~. Nil fields never generate a meta tag. Fields which are Nil by default are generally optional.
  • The image, audio, and video fields must result in a fully qualified url. This is handled for local files automatically, but you must also add the file to dontRev in gulpfile.js. For externally hosted files, you must modify app/partials/meta.static.hbs
  • Instead of the video field, you may specify a youtube video id.
  • The twitter fields are used for Twitter Cards, but you must enable them for your domain with Twitter first.

Contributing

Please submit and comment on bug reports and feature requests.

To submit a patch:

  1. Fork it (https://github.com/makenew/deck-bespoke.js/fork).
  2. Create your feature branch (git checkout -b my-new-feature).
  3. Make changes.
  4. Commit your changes (git commit -am 'Add some feature').
  5. Push to the branch (git push origin my-new-feature).
  6. Create a new Pull Request.

License

This software can be used freely, see The Unlicense. The copyright text appearing below and elsewhere in this repository is for demonstration purposes only and does not apply to this software.

Creative Commons License
deck-bespoke.js by Evan Sosenko is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License .
Based on a work at https://github.com/makenew/deck-bespoke.js .

Some content may be licensed under other terms where noted.

Warranty

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.