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 while staying flexible enough in structure and toolset to fit a wide 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 quality reports / linting with Jshint, CssLint, and CSSCSS
• Build process with asset minification, uglification, and revving

Requirements

The generator only needs Node and Ruby basics. It will install everything else itself.

• Node.js and npm
• Ruby 1.9+ and Bundler 

Quick start

• Make sure you have yo installed:     npm install -g yo
• Install the generator locally: npm install 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 (as in grunt server:build) to run the build process, start a server, and review your site before deployment.

Note for Windows users: if the server fails on launch try refreshing your browser or moving the lrSnippet in the Grunt connect task below other middleware. The issue is being addressed in generator-webapp.

grunt report

Reports are similar to tests, but they check code quality instead of functionality. grunt report checks javascript with Jshint and CSS with 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 to bust caches, and the final optimized site is output to the 'dist' folder. 

grunt (default) and individual tasks

grunt is a custom task that runs reports and then builds your site. There are many individual tasks and targets in the Gruntfile, all of which are available on the command line. It's often useful to run tasks like jshint:all and compass:server by themselves. Read through the Gruntfile to learn more, edit them when necessary, and set up some of your own.  

Bower, components, and Usemin

Bower is a front-end package manager. It's awesome. Use it to download and manage CSS, javascript, Sass, and Compass components to use in your site. 

Everything in the bower_components directory is available when running grunt server during development. But, to keep thing lean the Yeoman workflow doesn't copy the entire bower_components directory during the build process. To make sure the components you're using are added to the build use them inside of a Usemin block, or add them manually to the copy:dist task.

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 jekyll categories subgenerator
• Add grunt-bower-install

Release History

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