A gulp plugin to support Asciidoctor.js processing in gulp tasks.
This plugin can be used to integrate Asciidoctor processing in your gulp tasks. Here is a typical usage scenario:
const gulp = require('gulp')
const asciidoctor = require('@asciidoctor/gulp-asciidoctor')
function processAdocFiles (cb) {
gulp.src('/path/to/my/files/**/*.adoc')
.pipe(asciidoctor({}))
.pipe(gulp.dest('targetdir'))
cb()
}
function copyImages(cb) {
gulp.src('/path/to/my/files/**/*.jpg')
.pipe(gulp.dest('targetdir'))
cb()
}
exports.process = gulp.parallel(processAdocFiles, copyImages)
You can configure the plugin itself by adding options:
//...
.pipe(asciidoctor({
extension: '.htm'
}))
//...
And you can also configure the underlying Asciidoctor processor via the respective Asciidoctor options:
//...
.pipe(asciidoctor({
safe: 'secure', // unsafe, safe, server or secure
doctype: 'article', // book, inline
standalone: true, // true or false
attributes: ['showtitle']
}))
//...
The plugin also supports the Asciidoctor Template Converter
var path = require('path')
//...
.pipe(asciidoctor({
template_dirs: path.join(__dirname, 'templates')
}))
//...
The behaviour of the plugin can be controlled via options. There are options that tweak the behaviour of the Gulp plugin itself and options that control the underlying Asciidoctor processor.
The following options can be used to configure the Gulp plugin:
extension
-
Sets the output extension of the plugin. Defaults to '.html' if backend is 'html5' or undefined. Defaults to '.xml' if backend is 'docbook5'
cnv
-
Sets a custom converter that should be used for processing. Defaults to 'undefined'.
All options of the underlying Asciidoctor can be set. Please refer to the Converter options page to see which options are available.
However, the following Asciidoctor options:
-
mkdirs
-
to_dir
-
to_file
will be removed, since they do not make sense in a gulp processing chain.
If not set, the following options will be set to the default values described here
backend
-
Sets the converter backend to use. Defaults to 'html5'. As for now, only 'html5' and 'docbook5' is supported.
base_dir
-
The base directory for resolving relative resources. Defaults to the directory of the currently processed file
doctype
-
The doctype. May be 'article', 'book' or 'inline'. Defaults to 'article'
safe
-
The safe mode to use. May be 'unsafe', 'safe', 'server' or 'secure'. Defaults to 'unsafe'
standalone
-
Should headers and footers be included. Defaults to 'true'
Do not forget to set the Asciidoctor option base_dir
if you want to include
files from locations that are non-relative to the currently processed file.
The 'old' option 'header_footer' will be skipped in favor of the new option 'standalone'.
-
If 'header_footer' is set and 'standalone' is not set, the processor will receive 'standalone' = value of 'header_footer' option and the option 'header_footer' will be stripped.
-
If both 'header_footer' and 'standalone' are set, the option 'header_footer' will be stripped.
-
v2.2.5: Backend 'docbook5' is now supported
-
V2.2.0: upgrade to asciidoctor 2.2.0
-
V2.1.1: upgrade to asciidoctor 2.1.1, mocha 7.1.0 and replaced gulp-util with replace-ext and plugin-error
-
v1.5.5-4: upgrade asciidoctor.js to version 1.5.5-4 and use version consistent with asciidoctor.js.
-
v1.0.8: upgrade asciidoctor.js to version 1.5.5-1 and other deps to latest.
-
v1.0.7: clean dependences(remove gulp and gulp-debug).
-
v1.0.6: bug fixed
-
v1.0.5: fix asciidoctor.js default init bug (Jan/11/2015)
-
v1.0.4: bug fixed (Jan/11/2015)
-
v1.0.3: bug fixed (Jan/8/2015)
-
Initialize asciidoctor.js only once (Thanks Amr Mostafa)
-
-
v1.0.2: update to asciidoctor 1.5.2