npm package: @henriette-einstein/asciidoc-converter-handlebars
Description: An AsciiDoc custom converter that uses the Handlebars template engine
Author: Armin Pfarr
Latest version: 0.9.0

# asciidoctor-converter-handlebars

A custom converter for AsciiDoctor that uses the Handlbars template engine.

## Installation

To install the converter in your project use

```
yarn add @henriette-einstein/asciidoc-converter-handlebars
```

or

```
npm i @henriette-einstein/asciidoc-converter-handlebars
```

## Usage

### Usage with Handlebar template strings

To invoke the converter using a string containing a handlebars template use

```js
const path = require('path')
const asciidoctor = require('asciidoctor')()
const TemplateConverter = require('asciidoc-converter-handlebars')

const baseConverter = asciidoctor.Html5Converter.create()

// Instantiate the tempalte here
let converter = new TemplateConverter(baseConverter)
// let the template listen to the 'document' node name with the
// given template string
const templateString =
  '<html><head><title>{{attributes.doctitle}}</title></head></html>'
converter.addTemplate('document', templateString)

// register the converter
asciidoctor.ConverterFactory.register(converter, ['html5'])

// convert the file
const result = asciidoctor.convertFile(
  path.join(__dirname, '<FILE_NAME>'),
  { to_file: false, header_footer: true } // any AsciiDoctor option you need
)
```

### Usage with Handlebar template files

To invoke the converter using a Handlebar template written in a file

```js
const path = require('path')
const asciidoctor = require('asciidoctor')()
const TemplateConverter = require('asciidoc-converter-handlebars')

const baseConverter = asciidoctor.Html5Converter.create()

// Instantiate the tempalte here
let converter = new TemplateConverter(baseConverter)
// let the template listen to the 'document' node name with
// the template stored in the given file
converter.addTemplateFile(
  'document',
  path.join(__dirname, '<YOUR PATH GOES HERE>')
)

// register the converter
asciidoctor.ConverterFactory.register(converter, ['html5'])

// convert the file
const result = asciidoctor.convertFile(
  path.join(__dirname, '<FILE_NAME>'),
  { to_file: false, header_footer: true } // any AsciiDoctor option you need
)
```

### Usage with a directory containing Handlebar templates

If you are too lazy to add every single template you need by invoking
`addTemplateFile()`, place all your template files in a directory. Then
you only have to call `addTemplateDirectory()` once, to add all
template files.

The name of the template file without the extension will be used as the
node name you want to listen to.

For example `document.hbs` will be called for the node name `document`, `section.hbs' for the node name`section`.

```js
const path = require('path')
const asciidoctor = require('asciidoctor')()
const TemplateConverter = require('asciidoc-converter-handlebars')

const baseConverter = asciidoctor.Html5Converter.create()

// Instantiate the tempalte here
let converter = new TemplateConverter(baseConverter)
// compile and add the templates stored in the given directory
converter.addTemplateDirectory(
  path.join(__dirname, '<YOUR DIRECTORY PATH GOES HERE>')
)

// register the converter
asciidoctor.ConverterFactory.register(converter, ['html5'])

// convert the file
const result = asciidoctor.convertFile(
  path.join(__dirname, '<FILE_NAME>'),
  { to_file: false, header_footer: true } // any AsciiDoctor option you need
)
```