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.
Common problems? Common questions? Check out the FAQ.md
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 BrowserSync
- 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
- generator-jekyllrb requires Node.js
>= 0.10
, Ruby>= 1.9
- Install the generator:
npm install -g generator-jekyllrb
- Run:
yo 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 jekyll doctor
.
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
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
on its own is a special task that runs grunt check
, any tests you've added, and grunt build
.
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 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.
Getting started with Yeoman
Getting started with Grunt
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
compass
task 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
usemin
blocks should match the paths you entered during setup, as these are now expected byusemin
,autoprefixer
and other task configurations in your Gruntfile. - Test that everything is working correctly by running
grunt serve
,grunt dist
, andgrunt 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.
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
).
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');
}
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.