{"id":15689766,"url":"https://github.com/jonschlinkert/hekyll","last_synced_at":"2025-10-20T07:58:08.061Z","repository":{"id":57262355,"uuid":"94481200","full_name":"jonschlinkert/hekyll","owner":"jonschlinkert","description":"Migrate Jekyll (gh-pages) themes to use handlebars instead of liquid.","archived":false,"fork":false,"pushed_at":"2017-09-22T01:04:26.000Z","size":121,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-07T23:08:57.228Z","etag":null,"topics":["assemble","blog","convert","converter","gh-pages","github-pages","handlebars","jekyll","liquid","migrate","migrator","pages","site","templates","theme"],"latest_commit_sha":null,"homepage":"https://github.com/jonschlinkert","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonschlinkert.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":".github/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-15T21:44:39.000Z","updated_at":"2017-08-16T20:19:21.000Z","dependencies_parsed_at":"2022-08-25T02:50:36.881Z","dependency_job_id":null,"html_url":"https://github.com/jonschlinkert/hekyll","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonschlinkert%2Fhekyll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonschlinkert%2Fhekyll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonschlinkert%2Fhekyll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonschlinkert%2Fhekyll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonschlinkert","download_url":"https://codeload.github.com/jonschlinkert/hekyll/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252968118,"owners_count":21833252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assemble","blog","convert","converter","gh-pages","github-pages","handlebars","jekyll","liquid","migrate","migrator","pages","site","templates","theme"],"created_at":"2024-10-03T18:04:24.817Z","updated_at":"2025-10-20T07:58:03.019Z","avatar_url":"https://github.com/jonschlinkert.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hekyll [![NPM version](https://img.shields.io/npm/v/hekyll.svg?style=flat)](https://www.npmjs.com/package/hekyll) [![NPM monthly downloads](https://img.shields.io/npm/dm/hekyll.svg?style=flat)](https://npmjs.org/package/hekyll) [![NPM total downloads](https://img.shields.io/npm/dt/hekyll.svg?style=flat)](https://npmjs.org/package/hekyll) [![Linux Build Status](https://img.shields.io/travis/jonschlinkert/hekyll.svg?style=flat\u0026label=Travis)](https://travis-ci.org/jonschlinkert/hekyll)\n\n\u003e Migrate Jekyll (gh-pages) themes to use handlebars instead of liquid.\n\nFollow this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), for updates on this project and others.\n\n## Install\n\nInstall with [npm](https://www.npmjs.com/):\n\n```sh\n$ npm install --save hekyll\n```\n\n## Usage\n\n### Quickstart\n\nThe easiest way to use hekyll is to call the static `.build` method with an options object.\n\n**Required options**\n\nAt minimum, you will need to define the following:\n\n* `options.cwd` - the source directory with the jekyll theme to convert\n* `options.destBase` - the base destination directory to write the converted or copied files to.\n\n**Example**\n\n```js\nvar Hekyll = require('hekyll');\n\nHekyll.build({cwd: 'jekyll_theme_folder', destBase: 'output_folder'})\n  .then(function() {\n    console.log('converted!');\n  })\n  .catch(console.error);\n```\n\n### Custom\n\nThe 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.\n\n**Example**\n\n```js\nvar Hekyll = require('hekyll');\nvar hekyll = new Hekyll({\n  cwd: 'jekyll_theme_folder',\n  destBase: 'output_folder'\n});\n\nfunction dest(dir) {\n  return function(file) {\n    return dir || '';\n  };\n}\n\nhekyll.templates([\n  `{,_*/**/}*.{html,markdown,mdown,mkdown,mkdn,mkd,md,textile,liquid}`,\n  '!**/{README*,LICENSE*,CONTRIBUTING*}'\n], dest())\n  .then(hekyll.assets('{assets,public}/**', dest()))\n  .then(hekyll.copy('_config.yml', dest()))\n  .then(hekyll.copy('_data/**', dest('_data')))\n  .then(hekyll.copy('_sass/**', dest('_sass')))\n  .then(hekyll.copy('styles.scss', {addImport: 'custom'}, dest('_sass')))\n  .then(hekyll.copy('**/*.{xml,txt}', function(file) {\n    file.extname += '.hbs';\n    return '';\n  }))\n  .then(hekyll.text(dest()))\n  .then(function() {\n    console.log('done!');\n  })\n  .catch(console.error)\n```\n\n**Required Options**\n\n* `cwd`: the directory with source files for a Jekyll theme.\n* `destBase`: the base destination directory for the converted theme.\n\n## API\n\n### [Hekyll](index.js#L20)\n\nCreate an instance of `Hekyll` with the given `options`.\n\n**Params**\n\n* `options` **{Object}**\n\n**Example**\n\n```js\nvar Hekyll = require('hekyll');\nvar hekyll = new Hekyll();\n```\n\n### [.templates](index.js#L42)\n\nCopies and converts liquid templates to handlebars templates using the given glob `patterns`, `options` and `dest` function.\n\n**Params**\n\n* `patterns` **{String|Array}**\n* `options` **{Object}**\n* `dest` **{Function}**: Must return a string.\n* `returns` **{Promise}**\n\n**Example**\n\n```js\nhekyll.templates(patterns, {destBase: 'foo'}, function(file) {\n  // optionally do stuff to vinyl \"file\" object\n  // the returned folder is joined to `options.destBase`\n  return 'folder_name';\n});\n```\n\n### [.copy](index.js#L98)\n\nCopies files using the given glob `patterns`, `options` and `dest` function. Converts liquid templates and strips front matter from files.\n\n**Params**\n\n* `patterns` **{String|Array}**\n* `options` **{Object}**\n* `dest` **{Function}**: Must return a string.\n* `returns` **{Promise}**\n\n**Example**\n\n```js\nhekyll.copy(patterns, {destBase: 'foo'}, function(file) {\n  return '';\n});\n```\n\n### [.assets](index.js#L134)\n\nCopies assets files using the given glob `patterns`, `options` and `dest` function. Does not read the files or modify file contents in any way.\n\n**Params**\n\n* `patterns` **{String|Array}**\n* `options` **{Object}**\n* `dest` **{Function}**: Must return a string.\n* `returns` **{Promise}**\n\n**Example**\n\n```js\nhekyll.assets(patterns, {destBase: 'foo'}, function(file) {\n  return '';\n});\n```\n\n### [.text](index.js#L162)\n\nCopies plain text files using the given glob `patterns`, `options` and `dest` function. Strips front-matter, but does not attempt to convert templates.\n\n**Params**\n\n* `patterns` **{String|Array}**\n* `options` **{Object}**\n* `dest` **{Function}**: Must return a string.\n* `returns` **{Promise}**\n\n**Example**\n\n```js\nhekyll.text(patterns, {destBase: 'foo'}, function(file) {\n  return '';\n});\n```\n\n## Choosing a theme\n\n~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.\n\n**Handlebars helpers**\n\nTo 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.\n\nHere are some libraries that might be useful for this:\n\n* [template-helpers](https://github.com/jonschlinkert/template-helpers) - generic helpers that can be used with any template engine.\n* [handlebars-helpers](https://github.com/helpers/handlebars-helpers) - more than 150 handlebars helpers\n\n**Bug reports**\n\nIf 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.\n\n## About\n\n### Related projects\n\nYou might also be interested in these projects:\n\n* [assemble](https://www.npmjs.com/package/assemble): Get the rocks out of your socks! Assemble makes you fast at creating web projects… [more](https://github.com/assemble/assemble) | [homepage](https://github.com/assemble/assemble \"Get the rocks out of your socks! Assemble makes you fast at creating web projects. Assemble is used by thousands of projects for rapid prototyping, creating themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websit\")\n* [gulp-liquid-to-handlebars](https://www.npmjs.com/package/gulp-liquid-to-handlebars): Convert liquid templates to handlebars templates. There are so many resources for jekyll and liquid… [more](https://github.com/jonschlinkert/gulp-liquid-to-handlebars) | [homepage](https://github.com/jonschlinkert/gulp-liquid-to-handlebars \"Convert liquid templates to handlebars templates. There are so many resources for jekyll and liquid on github, but handlebars is a better engine for javascript. \")\n* [liquid-to-handlebars](https://www.npmjs.com/package/liquid-to-handlebars): Convert liquid templates to handlebars templates. | [homepage](https://github.com/jonschlinkert/liquid-to-handlebars \"Convert liquid templates to handlebars templates.\")\n\n### Contributing\n\nPull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).\n\nPlease read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.\n\n### Building docs\n\n_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_\n\nTo generate the readme, run the following command:\n\n```sh\n$ npm install -g verbose/verb#dev verb-generate-readme \u0026\u0026 verb\n```\n\n### Running tests\n\nRunning 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:\n\n```sh\n$ npm install \u0026\u0026 npm test\n```\n\n### Author\n\n**Jon Schlinkert**\n\n* [github/jonschlinkert](https://github.com/jonschlinkert)\n* [twitter/jonschlinkert](https://twitter.com/jonschlinkert)\n\n### License\n\nCopyright © 2017, [Jon Schlinkert](https://github.com/jonschlinkert).\nReleased under the [MIT License](LICENSE).\n\n***\n\n_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.6.0, on September 21, 2017._","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonschlinkert%2Fhekyll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonschlinkert%2Fhekyll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonschlinkert%2Fhekyll/lists"}