generator-jekyllrb

Generator-jekyllrb

Supercharge Jekyll development with Yeoman. Yo, Jekyllrb!

Generator-jekyllrb wraps the Jekyll static site generator in a Yeoman development workflow. Scaffold your site with Yo, manage front end packages with Bower, and automate development and build tasks with Grunt.

Generator-jekyllrb is ideal for developing performant static sites and prototyping dynamic sites and apps (especially if the final version uses Yeoman too). It's also a great introduction to Yeoman if you're not familiar with JavaScript MV* frameworks.

Features

During setup you can choose:

• Compass, Sass, Stylus with Nib, or vanilla CSS
• CoffeeScript or vanilla JavaScript
• Optional CSS vendor prefixing with Autoprefixer
• Default Jekyll or HTML5 Boilerplate templates
• Common Jekyll configuration options

Generator-jekyllrb always includes:

• Built in preview server with LiveReload
• Automatic Jekyll and preprocessor compiling
• Code quality checks with Jshint, CssLint, CSSCSS, and jekyll doctor
• An automatic build process that includes concatenation, image optimization, CSS and HTML minification, JS uglification, and asset revving to bust those caches

Getting Started

• Check that you have Node.js, Ruby, and Bundler installed
• Install the generator: npm install -g generator-jekyllrb
• Run: yo jekyllrb

Grunt Workflow

grunt server

Compiles all files and opens the site in your default browser. A watch task watches for changes to files, recompiles if necessary, and injects the changes into the browser with LiveReload.

grunt check

Checks code quality with Jshint, CSS Lint and CSSCSS, and Jekyll health with jekyll doctor.

grunt build

Builds an optimized site to the dist directory. Usemin blocks are concatenated, CSS, images, and HTML are minified, JavaScript is uglified, and assets are revved for cache busting.

grunt server:dist will run grunt build and open the result in your default browser

grunt (default)

grunt on its own is a special task that runs code checks, any tests you've added, and builds the site.

Individual tasks and :targets

Every task and target in the Gruntfile can be run individually (e.g., grunt jshint:all or grunt compass:server). Edit the tasks and add new ones to fit your needs.

Bower, components, and Usemin

Bower is a package manager for front-end components. Use it to download and manage CSS, JavaScript, and preprocessor tools for your site. Everything in the _bower_components directory is available while running grunt server.

To include components in the build, place them inside of a Usemin block or add them to the copy:dist task. This workflow will be streamlined with the release of Usemin 2.0.

More on Yeoman and Grunt

Getting started with Yeoman
Getting started with Grunt

Migrating an existing site

Wrapping an existing site in Yeoman isn't hard, but it takes a little manual editing.

1. Generate a new Yeoman/Jekyll app with the same tools and directory structure as your own. Ignore the templating options.
2. Transfer any custom configuration from your _config.yml to the newly generated _config.yml.
3. If you're using Compass, transfer custom configuration from your config.rb to the compass task in the Gruntfile.
4. Delete everything inside the Yeoman app directory.
5. Delete your site's original _config.yml, config.rb, and any files generated by Jekyll, CSS preprocessors, or CoffeeScript. Copy the remaining site into the app directory
6. Test that everything is working correctly by running grunt server, grunt dist, and grunt server:dist. Check that the files you expect are being transferred to the dist directory.
7. If you were versioning the _site directory, move its .git folder to the dist directory.

Contribute

Post bugs and feature requests to the Github issue tracker. In lieu of a formal styleguide, take care to maintain the existing coding style. Lint and test your code using Grunt.

Release History

Changelog

License

BSD-new