Gatsby-transformer-asciidoc NPM

gatsby-transformer-asciidoc

Parses AsciiDoc files using Asciidoctor.js.

Install

npm install gatsby-transformer-asciidoc

How to use

// In your gatsby-config.js
plugins: [`gatsby-transformer-asciidoc`]

A full explanation of asciidoc can be found here: Asciidoctor.js

You can also pass all Asciidoctor's convert options to the transformer. An example would be:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-asciidoc`,
    options: {
      attributes: {
        showtitle: true,
      },
    },
  },
]

Parsing algorithm

It recognizes files with the following extensions as AsciiDoc:

adoc
asciidoc

Additional extensions can be configured via the fileExtensions option:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-asciidoc`,
    options: {
      attributes: {
        showtitle: true,
      },
      fileExtensions: [`ad`, `adoc`],
    },
  },
]

Each AsciiDoc file is parsed into a node of type asciidoc.

Set imagesdir

You also can define where the asciidoc file can find the images by setting the imagesdir attribute.

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-transformer-asciidoc`,
    options: {
      attributes: {
        imagesdir: `/images`,
      },
    },
  },
]

In the asciidoc file you can insert your image just by using: image::myimage.png[]

NOTE

If no imagesdir is set the default value is /images@
Don't use relative images paths because the images might not be copied automatically to the location where the converted asciidoc html file will to located.
In case a pathPrefix is set it will altered the images location.
In case you want to be able to override the defined imagesdir inside of your asciidoc file you have to end the path with a @ (e.g. /images@).

How to query

A sample GraphQL query to get AsciiDoc nodes:

{
  allAsciidoc {
    edges {
      node {
        html
        document {
          title
          subtitle
          main
        }
        author {
          fullName
          firstName
          lastName
          middleName
          authorInitials
          email
        }
        revision {
          date
          number
          remark
        }
      }
    }
  }
}

Add new node attributes in the asciidoc file

You can define in the asciidoc file your own data that will be automatically be attached to the node attributes.

Example

= AsciiDoc Article Title
Firstname Lastname <author@example.org>
1.0, July 29, 2018, Asciidoctor article template

:page-title: Article
:page-path: /my-blog-entry
:page-category: My Category

Each attribute with the prefix page- will be automatically added under pageAttributes so it can be used with GraphQL.

{
  allAsciidoc {
    edges {
      node {
        pageAttributes {
          title
          path
          category
        }
      }
    }
  }
}

Define a Custom Converter

You can define a custom converter by adding the converterFactory option.

// In your gatsby-config.js, make sure to import or declare CustomConverter
plugins: [
  {
    resolve: `gatsby-transformer-asciidoc`,
    options: {
      converterFactory: CustomConverter,
    },
  },
]

CustomConverter is a custom javascript class you'll need to create. Information on how to write a custom CustomConverter can be found at the asciidoctor docs.

In the example below, we will use a custom converter to convert paragraphs but the other nodes will be converted using the built-in HTML5 converter:

const asciidoc = require(`asciidoctor`)()

class CustomConverter {
  constructor() {
    this.baseConverter = asciidoc.Html5Converter.$new()
  }

  convert(node, transform) {
    if (node.getNodeName() === "paragraph") {
      return `<p>${node.getContent()}</p>`
    }

    return this.baseConverter.convert(node, transform)
  }
}

gatsby-transformer-asciidoc takes then this class, not a instance of CustomConverter, as the converterFactory option. You can also reuse the internal converter of gatsby-transformer-asciidoc, since the constructor of a given CustomConverter will be call with it as parameter.