generator-jekyllrb

Generator-jekyllrb

A Yeoman generator, workflow, and build system for the Jekyll static site generator. Yo, Jekyllrb!

Generator-jekyllrb wraps the Jekyll static site generator in a Yeoman development workflow. Scaffold a site with Yo, manage front end packages with Bower, and run development and build tasks with Grunt. Generator-jekyllrb aims to provide a solid baseline for modern development with a flexible structure and toolset to accommodate a variety of developer preferences. It's also a great way to get familiar with Yeoman generators and workflow if you don't know any javascript MVx frameworks.

Generator options:

• Default Jekyll or HTML5 Boilerplate templates
• Fully configurable directory structure
• Compass, Sass, or vanilla CSS
• Autoprefixer CSS post-processor
• Coffeescript or vanilla javascript
• Common Jekyll configuration options

Workflow features:

• Built in server with livereload
• Code linting with Jshint, CssLint, and CSSCSS
• Build process with asset minification, uglification, and revving

Requirements

Just the basics: Node.js and npm, Ruby 1.9+ and Bundler. The generator will install everything else.

Quick start

• Install the Yeoman tools: npm install -g yo grunt-cli bower
• Install the generator: npm install -g generator-jekyllrb
• Run: yo jekyllrb

Workflow

Once you've scaffolded your site there are some handy Grunt tasks available to help you develop, test, and build.

grunt server

This is your development workhorse. Running grunt server starts a watch task for preprocessor files, starts a server, and opens the site in your default browser. The server uses livereload to inject code changes into the browser automatically — there's no need to manually refresh.

You can use the :build target (grunt server:build) to run the build process, start a server, and review your site before deployment.

grunt report

Reports are similar to tests, but they check code quality instead of functionality. grunt report checks code with Jshint, CSS Lint and CSSCSS. BAMF! You just became a better developer. 

You can configure report options in the Gruntfile or the task's '.rc' files.

grunt build

When you're ready to publish your site, run grunt build to send it through a build process. Usemin blocks are concatenated, CSS, images, and HTML are minified, javascript is uglified, assets are revved, and the final optimized site is output to the 'dist' directory. 

grunt (default) and individual tasks

grunt is a custom task that runs reports and then builds your site.

There are many tasks and targets in the Gruntfile, all of which are available for individual use on the command line. Read through the Gruntfile to familiarize yourself with the complete list; it can be very useful to run tasks like jshint:all and compass:server by themselves. Edit them when necessary, and set up some of your own.  

Bower, components, and Usemin

Bower is a package manager for front-end components. Use it to download and manage CSS, javascript, and preprocessor components for your site. Everything in your 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 manually to the copy:dist, uglify, and cssmin tasks. This workflow will be streamlined with the release of Usemin 2.0.

Migrating an existing site

Using the generator's Yeoman workflow with an existing site is easy, but requires a little manual editing.

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

Contribute

Report bugs and feature proposals in 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.

To Do

• Add deployment options
• Add stylus and require.js
• Add a categories subgenerator
• Add grunt-bower-install

Release History

0.3.4, June 24, 2013: Refinements, update to grunt-jekyll 3.8.
0.3.3, June 20, 2013: Minor improvements.
0.3.2, June 16, 2013: Update livereload, improve usemin workflow.
0.3.1, June 13, 2013: Remove stray debug code.
0.3.0, June 13, 2013: Switch to Generator 0.12, new prompt, simplify Gruntfile.
0.2.8, June 12, 2013: Fix race condition bug (Issue #11).
0.2.7, June 4, 2013: Update grunt-csscss to test (s)css directories, improve readme.
0.2.6, June 1, 2013: Coffeescript bugfixes.
0.2.5, June 1, 2013: Improve Sass and Autoprefixer tasks.
0.2.4, May 31, 2013: Minor improvements, documentation update.
0.2.3, May 30, 2013: Documentation update.
0.2.2, May 30, 2013: Gruntfile and Bower workflow refinement.
0.2.1, May 30, 2013: Bugfixes.
0.2.0, May 29, 2013: Add Autoprefixer, rewrite Grunt workflow, bugfixes.
0.1.3, May 29, 2013: Bugfixes.
0.1.2, May 24, 2013: Documentation updates, name change.
0.1.1, May 21, 2013: Documentation updates.
0.1.0, May 21, 2013: Initial release.

License

BSD-new License