How to register asciidoctor.js extensions?

[chtenb]

We can set attributes using the asciidoc.preview.attributes option, like 'source-highlighter': 'highlightjs-ext',. However, this particular highlighter is an extension which is normally registered like highlightJsExt.register(asciidoctor.Extensions) in a asciidoctor.js script. How do I make sure that this plugin is registered in asciidoctor-vscode?

[danyill]

We don't currently have a mechanism for registering custom extensions in this extension. We need to provide additional user settings to allow custom extensions to be registered and applied to documents.

What would you want this feature to look like?

• Do you use extensions on a per folder or per workspace basis?
• For an initial implementation, would it be sufficient to have a "Use extensions" option and then perhaps a field for comma delimited references to absolute paths to modules which export a register function (e.g. like asciidoctor-chart).

I'm not sure if there would be difficulties calling extensions from within the extension at run-time but I think after the next release I'd be keen to look into this issue.

[chtenb]

Personally I used it on a per-workspace basis. I have a project which uses asciidoctor extensively and uses the following script to produce html. In my usecase it would be nice if the VSCode preview would match the output of this script, because right now the VSCode preview doesn't work well enough for me. The difference is too big w.r.t. my eventual html output.

For an initial implementation, would it be sufficient to have a "Use extensions" option and then perhaps a field for comma delimited references to absolute paths to modules which export a register function (e.g. like asciidoctor-chart).

That sounds okay.

Would it be hard to hook a script like below into the extension? That way everyone can just do whatever they want. Maybe it would need to have a standardized name, like asciidoctor.rc.js or something.

const Asciidoctor = require('asciidoctor')
const kroki = require('asciidoctor-kroki')
const highlightJsExt = require('asciidoctor-highlight.js')
const glob = require('glob')

var asciidoctor = Asciidoctor()

kroki.register(asciidoctor.Extensions)
highlightJsExt.register(asciidoctor.Extensions)

var options = {
  'safe': 'unsafe',
  'standalone': true,
  'attributes': {
    'linkcss': true,
    'source-highlighter': 'highlightjs-ext',
    'docinfodir': '../res/',
    'docinfo': 'shared',
    'stylesheet': '../res/asciidoc.css',
    'kroki-default-options': 'inline',
    'allow-uri-read': true
  }
}

if (process.argv[2]) {

  options['to_file'] = false
  var html = asciidoctor.convertFile(process.argv[2], options)
  console.log(html)

} else {

  glob('blog/*.adoc', function (err, files) {
    if (err) {
      console.log(err)
    } else {
      files.forEach(function (file) {
        asciidoctor.convertFile(file, options)
      });
    }
  });

}

[danyill]

We'll have a go soon!

I think we could also have a go at providing variable substitution to give flexibility.

[YoshihideShirai]

I created PR for this solution. https://github.com/asciidoctor/asciidoctor-vscode/pull/569

Give v3.0.0(Pre-release version) a try.