# grunt-jekyll
[](https://www.npmjs.com/package/grunt-jekyll)
[](https://travis-ci.org/dannygarcia/grunt-jekyll)
[](https://david-dm.org/dannygarcia/grunt-jekyll)
[](https://david-dm.org/dannygarcia/grunt-jekyll#info=devDependencies)
[](https://www.npmjs.com/package/grunt-jekyll)
> Compile [Jekyll](http://jekyllrb.com/) sites with [Grunt](http://gruntjs.com/).
## Getting Started
This plugin requires [Grunt](http://gruntjs.com/) `~0.4.0` and [Jekyll](http://jekyllrb.com/) `>= v1.0.0`.
If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide which explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process you may install this plugin with the command:
```shell
npm install grunt-jekyll --save-dev
```
After the plugin has been installed, load it in your Gruntfile with:
```js
grunt.loadNpmTasks('grunt-jekyll');
```
## Jekyll Task
_Run this task with the `grunt jekyll` command._
This task helps you compile your Jekyll static site with Grunt.
### Jekyll Subcommands
#### serve
Type: `boolean`
Default: `false`
Build the site and start a Jekyll development server on `http://localhost:4000`. The server lasts forever: kill it with Ctrl + C.
If `serve` is false, the site is built with the `build` command.
For complex projects you may want to use [grunt-contrib-connect](https://github.com/gruntjs/grunt-contrib-connect) or [grunt-browser-sync](https://github.com/BrowserSync/grunt-browser-sync) instead.
#### doctor
Type: `boolean`
Default: `false`
Test your site for common errors and deprecated code. Ignores all other options except `src`, `config`, and `bundleExec`.
### Options
You can use all of the configuration options available in the [Jekyll Documentation](http://jekyllrb.com/docs/configuration/), as well as some special options provided by this plugin.
#### src
Type: `string`
Default: `.`
Directory where Jekyll will read files.
#### dest
Type: `string`
Default: `./_site`
Directory where Jekyll will write files.
#### [no_]watch
Type: `boolean`
Default: `false`
Regenerate the site when files are modified.
If you are running multiple watch tasks in a project you should use [grunt-contrib-watch](https://github.com/gruntjs/grunt-contrib-watch) instead.
#### config
Type: `string`
Default: `_config.yml`
Specify a custom configuration file. Multiple files separated by a comma will cascade right to left.
#### raw
Type: `string`
Create a temporary \_config.yml with the contents of `raw`. This config file has greater precedence than the files in `config`.
#### safe
Type: `boolean`
Default: `false`
Disables custom plugins, and ignore symbolic links.
#### plugins
Type: `string`
Default: `./_plugins`
Specify a plugins directory.
#### layouts
Type: `string`
Default: `./_layouts`
Specify a layouts directory.
#### drafts
Type: `boolean`
Default: `false`
Process and render draft posts.
#### future
Type: `boolean`
Default: `false`
Publishes posts with a future date.
#### lsi
Type: `boolean`
Default: `false`
Produce an index for related posts.
#### limit_posts
Type: `number`
Limit the number of posts to parse and publish.
#### force_polling
Type: `boolean`
Force watch to use polling.
#### verbose
Type: `boolean`
Print verbose output.
#### quiet
Type: `boolean`
Silence the normal output from Jekyll during a build.
#### incremental
Type: `boolean`
Enable the experimental incremental build feature. Incremental build only re-builds posts and pages that have changed, resulting in significant performance improvements for large sites, but may also break site generation in certain cases.
#### livereload
Type: `boolean`
LiveReload refreshes your browser after a change.
#### port
Type: `string` or `number`
Listen on the given port (requires `serve`).
#### host
Type: `string`
Listen at the given hostname (requires `serve`).
#### baseurl
Type: `string`
Serve the website from the given base URL (requires `serve`).
#### skip_initial_build
Type: `boolean`
Skips the initial site build which occurs before the server is started.
#### open_url
Type: `boolean`
Opens the local URL in your default browser.
#### bundleExec
Type: `boolean`
Default: `false`
Run `jekyll` with [bundle exec](http://gembundler.com/v1.3/man/bundle-exec.1.html).
## Usage examples
Follow [this Grunt example](https://gist.github.com/3753650) to get started with grunt-jekyll right away.
### Example config
```js
grunt.initConfig({
jekyll: { // Task
options: { // Universal options
bundleExec: true,
src : '<%= app %>'
},
dist: { // Target
options: { // Target options
dest: '<%= dist %>',
config: '_config.yml,_config.build.yml'
}
},
serve: { // Another target
options: {
serve: true,
dest: '.jekyll',
drafts: true,
future: true
}
}
}
});
grunt.loadNpmTasks('grunt-jekyll');
grunt.registerTask('default', ['jshint', 'jekyll']);
```
### Example usage
#### Use the `raw` option
```js
grunt.initConfig({
jekyll: {
dist: {
options: {
config: '_config.yml',
// Construct a string with JavaScript.
// Remember, in YAML line breaks and indentation matter.
raw: 'pygments: false\n' +
'exclude: [\'development\']\n' +
'author:\n' +
' name: ' + fetchAuthor() + '\n' +
' email: ' + fetchEmail()
}
}
}
});
```
## Changelog
- v0.4.3: More options support for Jekyll 3.0.0
- v0.4.2: More internal optimizations.
- v0.4.1: Internal optimizations.
- v0.4.0: Added setup for tests.
- v0.3.9: Consolidating branches and bumping version number.
- v0.3.8: Added [@robwierzbowski](https://github.com/robwierzbowski)'s raw option and other PRs.
- v0.3.6:
- Reviewed Jekyll's [source](https://github.com/mojombo/jekyll/blob/master/bin/jekyll) and updated plugin with new flags.
- Reviewed and warned about deprecated flags.
- Updated documentation to match flag updates. (Rewritten as a list)
- v0.3.3: Updated link in documentation. Added to-do list.
- v0.3.2: Added option to select config file. Removed deprecated `--pygments` option flag. Bugfixes.
- v0.3.0: Update for Jekyll 1.0
- v0.2.1: Fixed destination path option.
- v0.2.0: Updated README with better options. Options are more flexible.
- v0.1.6: Updated README with better example.
- v0.1.0: Initial Release.
## License
MIT