@asciidoctor-extender/asciidoctor.js-extender

asciidoctor.js-extender

The asciidoctor.js extender is a library for extending standard asciidoc with custom built plugins. It aims to be a platform which eases extension creation and inclusion for asciidoctor.js.

If you wish to submit a bug, contribute or request a feature please follow the guides at the end of this document.

##installation To include the library in your project run the following command:

npm install -S @asciidoctor-extender/asciidoctor.js-extender

Configuring the plugin

{
  "extensions": {
    "include": [
      "@asciidoctor-extender/adoc-ext-include-markdown",
      "@asciidoctor-extender/adoc-ext-include-scss"
    ]
  },
  "source": "test/test.adoc",
  "target": "target/test"
}

Base attributes

Name	Description
source	The source file for the documentation
target	The target file name (without extension) to write
extensions	The root for all extensions

Extension attributes

Name	Description
include	A list of include extensions

Creating an extension

Follow these guides for creating extensions. A base requirement for all extensions is that the package name starts with @asciidoctor-extender/ and that the main entry point is set. If the main entry point is not set the library falls back to ./plugin/index.ts.

For file inclusion

Include plugins handle file parsing based on the result of the handles callback which gets the file target (path) as a parameter. The processing of the file content is done by the process callback which gets the

• document parameter; which is a reference to the document it's handling,
• reader parameter; which is the document reader
• target parameter; which is a file reference to the targeted file.
• attributes parameter; which is an object containing the attributes as defined by the include declaration.

A sample include plugin (for markdown)

function isMarkdownHandler(target) {
    return target.endsWith('.md');
}

function markdownProcessor(doc, reader, target, attrs) {
    reader.pushInclude('This is where your markdown should be!', target, target, 1, attrs);
    return reader;
}

/**
 * Extension for the handling of markdown files. Converts markdown to AsciiDoc.
 */
function markdownInclusionExtension() {
    this.handles(isMarkdownHandler);
    this.process(markdownProcessor);
}

module.exports = markdownInclusionExtension;

This include extension will replace all include declarations referring to *.md files to the string value "This is where your markdown should be!".

Registering issues

Should something be awry please feel free to register a bug by creating an issue labeled "bug" with a clear description of what fails, what is expected and steps to reproduce the error.

Contributing

To contribute to this library you can fork the library, implement the feature and create a pull request. Then create an issue labeled "Contribution" with a clear description of the feature and a reference to the pull request.

Requesting new features

In order to request a new feature please open a new issue labeled "Feature request" and a clear description of the functionality that is requested.