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.
During setup you can choose:
- Compass, Sass, or vanilla CSS
- 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
- An automatic build process that includes concatenation, image optimization, CSS and HTML minification, JS uglification, and asset revving to bust those caches
- generator-jekyllrb requires Node.js
>= 0.10, Ruby
- Install the generator:
npm install -g generator-jekyllrb
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.
Checks code quality with Jshint and CSS Lint, and Jekyll health with
grunt serve:dist will run
grunt build and open the result in your default browser
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 build, and then commit and deploy your built code to the specified remote repository.
grunt on its own is a special task that runs
grunt check, any tests you've added, and
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
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
Migrating an existing site
Wrapping an existing site in Yeoman isn't hard, but it takes a little manual editing.
- Generate a new Yeoman/Jekyll app with the same tools and directory structure as your own. Ignore the templating options.
- Transfer any custom configuration from your _config.yml to the newly generated _config.yml.
- If you're using Compass, transfer custom configuration from your config.rb to the
compasstask in the Gruntfile.
- Delete everything inside the Yeoman app directory.
- 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.
- Wrap any asset references in your copied layout files with usemin blocks. The asset target paths you enter in
useminblocks should match the paths you entered during setup, as these are now expected by
autoprefixerand other task configurations in your Gruntfile.
- Test that everything is working correctly by running
grunt dist, and
grunt serve:dist. Check that the files you expect are being transferred to the dist directory.
- If you were versioning the _site directory, move its .git folder to the dist directory.
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 (
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.