Context and APIs

HonKits provides different APIs and contexts to plugins. These APIs can vary according to the HonKit version being used, your plugin should specify the engines.gitbook field in package.json accordingly.

Book instance

The Book class is the central point of HonKit, it centralize all access read methods. This class is defined in book.ts.

// Read configuration from book.json
var value = book.config.get('title', 'Default Value');

// Resolve a filename to an absolute path
var filepath = book.resolve('');

// Render an inline markup string
book.renderInline('markdown', 'This is **Markdown**')
    .then(function(str) { ... })

// Render a markup string (block mode)
book.renderBlock('markdown', '* This is **Markdown**')
    .then(function(str) { ... })

Output instance

:warning: This API is too internal and should probably be avoided as much as possible. It may be removed in the future.

The Output class represent the output/write process.

// Return root folder for the output
var root = output.root();

// Resolve a file in the output folder
var filepath = output.resolve('myimage.png');

// Convert a filename to an URL (returns a path to an html file)
var fileurl = output.toURL('mychapter/');

// Write a file in the output folder
output.writeFile('hello.txt', 'Hello World')
    .then(function() { ... });

// Copy a file to the output folder
output.copyFile('./myfile.jpg', 'cover.jpg')
    .then(function() { ... });

// Verify that a file exists
    .then(function(exists) { ... });

Page instance

A page instance represent the current parsed page.

// Title of the page (from SUMMARY)

// Content of the page (Markdown/Asciidoc/HTML according to the stage)

// Relative path in the book

// Absolute path to the file

// Type of parser used for this file
page.type ('markdown' or 'asciidoc')

Context for Blocks and Filters

Blocks and filters have access to the same context, this context is bind to the template engine execution:

    // Current templating syntax
    "ctx": {
        // For example, after a {% set message = "hello" %}
        "message": "hello"

    // Book instance
    "book" <Book>,

    // Output instance
    "output": <Output>

For example a filter or block function can access the current book using:

Context for Hooks

Hooks only have access to the <Book> instance using