Migrate Jekyll (gh-pages) themes to use handlebars instead of liquid.
Follow this project's author, Jon Schlinkert, for updates on this project and others.
Install with npm:
$ npm install --save hekyllThe 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 convertoptions.destBase- the base destination directory to write the converted or copied files to.
Example
var Hekyll = require('hekyll');
Hekyll.build({cwd: 'jekyll_theme_folder', destBase: 'output_folder'})
.then(function() {
console.log('converted!');
})
.catch(console.error);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 for more details.
Example
var Hekyll = require('hekyll');
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.
Create an instance of Hekyll with the given options.
Params
options{Object}
Example
var Hekyll = require('hekyll');
var hekyll = new Hekyll();Copies and converts liquid templates to handlebars templates using the given glob patterns, options and dest function.
Params
patterns{String|Array}options{Object}dest{Function}: Must return a string.returns{Promise}
Example
hekyll.templates(patterns, {destBase: 'foo'}, function(file) {
// optionally do stuff to vinyl "file" object
// the returned folder is joined to `options.destBase`
return 'folder_name';
});Copies files using the given glob patterns, options and dest function. Converts liquid templates and strips front matter from files.
Params
patterns{String|Array}options{Object}dest{Function}: Must return a string.returns{Promise}
Example
hekyll.copy(patterns, {destBase: 'foo'}, function(file) {
return '';
});Copies assets files using the given glob patterns, options and dest function. Does not read the files or modify file contents in any way.
Params
patterns{String|Array}options{Object}dest{Function}: Must return a string.returns{Promise}
Example
hekyll.assets(patterns, {destBase: 'foo'}, function(file) {
return '';
});Copies plain text files using the given glob patterns, options and dest function. Strips front-matter, but does not attempt to convert templates.
Params
patterns{String|Array}options{Object}dest{Function}: Must return a string.returns{Promise}
Example
hekyll.text(patterns, {destBase: 'foo'}, function(file) {
return '';
});~20 jekyll themes were tested during the creation of this library, including all of the poole/poole themes from @mdo, and all of the built-in gh-pages 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, I want this to work as seamlessly as possible.
You might also be interested in these projects:
- assemble: Get the rocks out of your socks! Assemble makes you fast at creating web projects… more | homepage
- gulp-liquid-to-handlebars: Convert liquid templates to handlebars templates. There are so many resources for jekyll and liquid… more | homepage
- liquid-to-handlebars: Convert liquid templates to handlebars templates. | homepage
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guide for advice on opening issues, pull requests, and coding standards.
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verbRunning and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm testJon Schlinkert
Copyright © 2017, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on September 21, 2017.