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, or vanilla CSS
• CoffeeScript or vanilla JavaScript
• Automatic 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 and/or CoffeeLint, CssLint, 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

• generator-jekyllrb requires Node.js >= 0.10, Ruby >= 1.9
• Install the generator: npm install -g generator-jekyllrb
• Run: yo jekyllrb

Grunt Workflow

grunt serve

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 and CSS Lint, 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 serve:dist will run grunt build and open the result in your default browser

grunt deploy

During scaffolding the generator gives you the option to configure grunt-build-control to version and deploy your built code to a remote repository. If you configure build-control, grunt deploy will run grunt check, grunt test, grunt build, and then commit and deploy your built code to the specified remote repository.

grunt (default)

grunt on its own is a special task that runs grunt check, any tests you've added, and grunt build.

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 serve.

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. Wrap any asset references in your copied layout files with usemin blocks. The asset target paths you enter in usemin blocks should match the paths you entered during setup, as these are now expected by usemin, autoprefixer and other task configurations in your Gruntfile.
7. Test that everything is working correctly by running grunt serve, grunt dist, and grunt serve:dist. Check that the files you expect are being transferred to the dist directory.
8. If you were versioning the _site directory, move its .git folder to the dist directory.

Notes

Nested asset directories and Jekyll

Jekyll can't exclude nested directories, so we must exclude all directories that match the innermost asset directory. For example, assets/css will exclude all directories named css from Jekyll compilation. This will cause issues if your site has a tag or category named css; if you're worried about accidental exclusions prefix all asset directories with an underscore (assets/_css).

Absolute path to assets in CSS

Since we revision assets such as images, make sure that your CSS calls them using their absolute path, so on grunt build those images will be replaced properly.

Incorrect:

body {
  background: url('../images/foo.jpg');
}

Correct:

body {
  background: url('/images/foo.jpg');
}

Contribute

Please read the contributing guidelines before posting an issue.

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