✨ resolves #925 configure template engines (#944)

Author: ggrossetie

docs/modules/extend/pages/converter/template-converter.adoc

@@ -250,3 +250,77 @@ An optional JSON of options.
 
 `helpers`::
 The functions and values exported from the _helpers.js_ file.
+
+== Template options
+
+You can configure the template engine using the `template_engine_options` option.
+Here's a few examples:
+
+[source,js]
+----
+const options = {
+  template_engine_options: {
+    nunjucks: {
+      autoescape: false
+    },
+    handlebars: {
+      noEscape: true
+    },
+    pug: {
+      doctype: 'xml'
+    },
+    ejs: {
+      delimiter: '?',
+      openDelimiter: '[',
+      closeDelimiter: ']'
+    }
+  }
+}
+----
+
+To find out which options you can use, please read the official documentation of your template engine:
+
+EJS::
+https://github.com/mde/ejs#options
+
+Handlebars::
+https://handlebarsjs.com/api-reference/compilation.html#handlebars-compile-template-options
+
+Nunjucks::
+https://mozilla.github.io/nunjucks/api.html#constructor
+
+Pug::
+https://pugjs.org/api/reference.html#options
+
+== Template cache
+
+For performance reasons, templates are cached, but you can disable this feature using the `template_cache` option:
+
+[source,js]
+----
+asciidoctor.convert(input, { template_cache: false })
+----
+
+It might be useful when you want to configure the same template directory with different options.
+In the following example, we want to an XML https://pugjs.org/language/doctype.html[doctype].
+We need to disable the cache otherwise the second conversion will not reconfigure the templates with the `doctype: 'xml'` option:
+
+[source,js]
+----
+const options = {
+  safe: 'safe',
+  doctype: 'inline',
+  backend: 'html5',
+  template_dir: '/path/to/templates/pug',
+  template_cache: false, // disable template cache
+}
+
+console.log(asciidoctor.convert(`image:cat.png[]`, options)) // <img src="cat.png"/>
+console.log(asciidoctor.convert('image:cat.png[]', Object.assign(options, {
+  template_engine_options: {
+    pug: {
+      doctype: 'xml'
+    }
+  }
+}))) // <img src="cat.png"></img>
+----

packages/core/lib/asciidoctor/js/asciidoctor_ext/node/template.rb

@@ -20,6 +20,7 @@ def initialize backend, template_dirs, opts = {}
     @templates = {}
     @template_dirs = template_dirs
     @engine = opts[:template_engine]
+    @engine_options = opts[:template_engine_options] || {}
     case opts[:template_cache]
     when true
       @caches = self.class.caches
@@ -181,7 +182,9 @@ def scan_dir template_dir, pattern, template_cache = nil
             if (enginesContext.nunjucks && enginesContext.nunjucks.environment) {
               env = enginesContext.nunjucks.environment
             } else {
-              env = nunjucks.configure(#{template_dir}, {})
+              var opts = self.engine_options['nunjucks'] || {}
+              delete opts.web // unsupported option
+              env = nunjucks.configure(#{template_dir}, opts)
               enginesContext.nunjucks = { environment: env }
             }
             template = Object.assign(nunjucks.compile(fs.readFileSync(file, 'utf8'), env), { '$file': function() { return file } })
@@ -191,24 +194,32 @@ def scan_dir template_dir, pattern, template_cache = nil
           %x{
             var fs = require('fs')
             var env
+            var opts = self.engine_options['handlebars'] || {}
             if (enginesContext.handlebars && enginesContext.handlebars.environment) {
               env = enginesContext.handlebars.environment
             } else {
               env = handlebars.create()
               enginesContext.handlebars = { environment: env }
             }
-            template = { render: env.compile(fs.readFileSync(file, 'utf8')), '$file': function() { return file } }
+            template = { render: env.compile(fs.readFileSync(file, 'utf8'), opts), '$file': function() { return file } }
           }
         when :ejs
           ejs = node_require 'ejs'
           %x{
             var fs = require('fs')
-            template = { render: ejs.compile(fs.readFileSync(file, 'utf8')), '$file': function() { return file } }
+            var opts = self.engine_options['ejs'] || {}
+            opts.filename = file
+            // unsupported options
+            delete opts.async
+            delete opts.client
+            template = { render: ejs.compile(fs.readFileSync(file, 'utf8'), opts), '$file': function() { return file } }
           }
         when :pug
           pug = node_require 'pug'
           %x{
-            template = { render: pug.compileFile(file), '$file': function() { return file } }
+            var opts = self.engine_options['pug'] || {}
+            opts.filename = file
+            template = { render: pug.compileFile(file, opts), '$file': function() { return file } }
           }
         when :js
           template = `{ render: require(file), '$file': function() { return file } }`

packages/core/spec/fixtures/templates/ejs-custom-delimiters/paragraph.ejs

@@ -0,0 +1 @@
+<p class="paragraph-ejs">[?= node.getContent() ?]</p>

packages/core/spec/fixtures/templates/pug/inline_image.pug

@@ -0,0 +1 @@
+img(src=node.getTarget())

packages/core/spec/fixtures/templates/pug/paragraph.pug

@@ -1 +1 @@
-p.paragraph-pug #{node.getContent()}
+p.paragraph-pug !{node.getContent()}

packages/core/spec/node/asciidoctor.spec.js

@@ -1570,9 +1570,10 @@ sample content`, opts)
           const opts = { extension_registry: registry }
           const doc = asciidoctor.load('img::image-name[]', opts)
           const images = doc.findBy((b) => b.getContext() === 'image')
-          expect(images.length).to.equal(1)
-          expect(images[0].getTitle()).to.equal('title')
-          expect(images[0].getCaption()).to.equal('caption')
+          expect(images).to.have.length(1)
+          const firstImage = images[0]
+          expect(firstImage.getTitle()).to.equal('title')
+          expect(firstImage.getCaption()).to.equal('caption')
           const result = doc.convert(opts)
           expect(result).to.contain('<img src="image-name.png" alt="image name">')
         })
@@ -2759,7 +2760,10 @@ content`
 </article>`)
       templateConverter.register('admonition', template)
       const templates = templateConverter.getTemplates()
-      const admonition = asciidoctor.Block.create(doc, 'admonition', { source: 'An admonition paragraph, like this note, grabs the reader’s attention.', attributes: { textlabel: 'Note' } })
+      const admonition = asciidoctor.Block.create(doc, 'admonition', {
+        source: 'An admonition paragraph, like this note, grabs the reader’s attention.',
+        attributes: { textlabel: 'Note' }
+      })
       expect(templates.admonition.render({ node: admonition })).to.equal(`<article class="message is-info">
   <div class="message-header">
     <p>Note</p>
@@ -2803,6 +2807,71 @@ And here&#8217;s a block image:</p>
 `, options)
       expect(result.replace(/\r/g, '').replace(/\n/g, '')).to.equal('<ul class="ulist"><p>foo</p><p>bar</p><p>baz</p></ul>')
     }).timeout(5000)
+    it('should configure Nunjucks environment using the template_engine_options', () => {
+      const options = {
+        safe: 'safe',
+        backend: 'html5',
+        template_dir: 'spec/fixtures/templates/nunjucks',
+        template_cache: false, // disable template cache to recreate templates with the given options
+        template_engine_options: {
+          nunjucks: {
+            autoescape: false,
+            web: {
+              async: true
+            }
+          }
+        }
+      }
+      const result = asciidoctor.convert('Simple paragraph with an inline image image:cat.png[]', options)
+      expect(result).to.equal('<p class="paragraph-nunjucks">Simple paragraph with an inline image <span class="image"><img src="cat.png" alt="cat"></span></p>')
+    })
+    it('should configure Handlebars environment using the template_engine_options', () => {
+      const options = {
+        safe: 'safe',
+        backend: 'html5',
+        template_dir: 'spec/fixtures/templates/handlebars',
+        template_cache: false, // disable template cache to recreate templates with the given options
+        template_engine_options: {
+          handlebars: {
+            noEscape: true
+          }
+        }
+      }
+      const result = asciidoctor.convert('Simple paragraph with an inline image image:cat.png[]', options)
+      expect(result).to.equal('<p class="paragraph-handlebars">Simple paragraph with an inline image <span class="image"><img src="cat.png" alt="cat"></span></p>')
+    })
+    it('should configure Pug templates using the template_engine_options', () => {
+      const options = {
+        safe: 'safe',
+        backend: 'html5',
+        template_dir: 'spec/fixtures/templates/pug',
+        template_cache: false, // disable template cache to recreate templates with the given options
+        template_engine_options: {
+          pug: {
+            doctype: 'xml'
+          }
+        }
+      }
+      const result = asciidoctor.convert('image:cat.png[]', options)
+      expect(result).to.equal('<p class="paragraph-pug"><img src="cat.png"></img></p>')
+    })
+    it('should configure EJS templates using the template_engine_options', () => {
+      const options = {
+        safe: 'safe',
+        backend: 'html5',
+        template_dir: 'spec/fixtures/templates/ejs-custom-delimiters',
+        template_cache: false, // disable template cache to recreate templates with the given options
+        template_engine_options: {
+          ejs: {
+            delimiter: '?',
+            openDelimiter: '[',
+            closeDelimiter: ']'
+          }
+        }
+      }
+      const result = asciidoctor.convert('A simple paragraph.', options)
+      expect(result).to.equal('<p class="paragraph-ejs">A simple paragraph.</p>')
+    })
     it('should resolve conflicts consistently when the same template exists in multiple directories', () => {
       // the template paragraph.njk is present in both the "nunjucks" and "nunjucks-ctx-b" directory!
       // the rule is that the last one wins so the template order in "template_dirs" is important.