## Usage

### Quickstart

The easiest way to use hekyll is to call the static `.build` method with an options object. 

**Required options**

At minimum, you will need to define the following:

- `options.cwd` - the source directory with the jekyll theme to convert
- `options.destBase` - the base destination directory to write the converted or copied files to.

**Example**

```js
var Hekyll = require('{%= name %}');

Hekyll.build({cwd: 'jekyll_theme_folder', destBase: 'output_folder'})
  .then(function() {
    console.log('converted!');
  })
  .catch(console.error);
```

### Custom

The main export is a constructor function that takes an options object. Once an instance is created, you can use hekyll's methods to convert and copy files however you want. See [the API documentation](#api) for more details.

**Example**

```js
var Hekyll = require('{%= name %}');
var hekyll = new Hekyll({
  cwd: 'jekyll_theme_folder',
  destBase: 'output_folder'
});

function dest(dir) {
  return function(file) {
    return dir || '';
  };
}

hekyll.templates([
  `{,_*/**/}*.{html,markdown,mdown,mkdown,mkdn,mkd,md,textile,liquid}`,
  '!**/{README*,LICENSE*,CONTRIBUTING*}'
], dest())
  .then(hekyll.assets('{assets,public}/**', dest()))
  .then(hekyll.copy('_config.yml', dest()))
  .then(hekyll.copy('_data/**', dest('_data')))
  .then(hekyll.copy('_sass/**', dest('_sass')))
  .then(hekyll.copy('styles.scss', {addImport: 'custom'}, dest('_sass')))
  .then(hekyll.copy('**/*.{xml,txt}', function(file) {
    file.extname += '.hbs';
    return '';
  }))
  .then(hekyll.text(dest()))
  .then(function() {
    console.log('done!');
  })
  .catch(console.error)
```

**Required Options**

- `cwd`: the directory with source files for a Jekyll theme.
- `destBase`: the base destination directory for the converted theme.

## API
{%= apidocs("index.js") %}

## Choosing a theme

~20 jekyll themes were tested during the creation of this library, including all of the [poole/poole themes](https://github.com/poole/poole) from [@mdo](https://github.com/mdo), and all of the built-in [gh-pages themes](https://pages.github.com/themes/). Most themes convert flawlessly, but some have nuances that might require some manual editing. 

**Handlebars helpers**

To be able to render the migrated templates with handlebars, you will first need to include any missing handlebars helpers that were converted from liquid filters and tags during the migration. 

Here are some libraries that might be useful for this:

- [template-helpers][] - generic helpers that can be used with any template engine.
- [handlebars-helpers][] - more than 150 handlebars helpers 


**Bug reports**

If you find a bug or something that doesn't convert correctly, [please let me know](../../issues/new), I want this to work as seamlessly as possible.