add support for custom templates (#616)

resolves #413
resolves #574

README.md

@@ -50,7 +50,8 @@ The preview supports setting AsciiDoc attributes through the `asciidoc.preview.a
 
 By default, the preview uses VS Code editor theme (`workbench.colorTheme`).
 To use Asciidoctor default style set the `asciidoc.preview.useEditorStyle` setting to `false`.
-It is also possible to set your own preview stylesheet with the `asciidoc.preview.style` setting.<br/>
+It is possible to set your own preview stylesheet with the `asciidoc.preview.style` setting.<br/>
+It is also possible to define custom templates with the `asciidoc.preview.templates` setting.<br/>
 (See more details under [Extension Settings](#extension-settings))
 
 ### Export as PDF

package.json

@@ -384,6 +384,16 @@
 						],
 						"scope": "resource"
 					},
+					"asciidoc.preview.templates": {
+						"type": "array",
+						"default": "",
+						"markdownDescription": "%asciidoc.preview.templates.desc%",
+						"items": {
+							"type": "string"
+						  },
+						  "uniqueItems": false,
+						"scope": "resource"
+					},
 					"asciidoc.use_kroki": {
 						"type": "boolean",
 						"default": false,
@@ -626,7 +636,7 @@
 		"asciidoctor-kroki": "0.15.4",
 		"uuid": "8.3.2",
 		"vscode-nls": "5.0.0",
-		"vscode-uri": "3.0.3"
+		"vscode-uri": "^3.0.3"
 	},
 	"__metadata": {
 		"id": "c1309cc2-f420-46a3-b2be-ca04f4d9e51b",

package.nls.json

@@ -30,6 +30,7 @@
 	"asciidoc.preview.openLinksToAsciidocFiles.desc": "Controls how links to other AsciiDoc files in the preview should be opened.",
 	"asciidoc.preview.openLinksToAsciidocFiles.inPreview": "Try to open links in the editor",
 	"asciidoc.preview.openLinksToAsciidocFiles.inEditor": "Try to open links in the preview",
+	"asciidoc.preview.templates.desc": "List of local paths to custom templates to use from the preview. Relative paths are interpreted relative to the folder open in the Explorer. If there is no open folder, they are interpreted relative to the location of the AsciiDoc file. All `\\` need to be written as `\\\\`.",
 
 	"asciidoc.pdf.title": "PDF",
 	"asciidoc.pdf.engine.desc": "Controls the PDF engine used to export as PDF.",

src/asciidocParser.ts

@@ -157,6 +157,7 @@ export class AsciidocParser {
     attributes['env-vscode'] = ''
 
     const baseDir = AsciidocParser.getBaseDir(doc.fileName)
+    const templateDirs = this.getTemplateDirs()
     const options: { [key: string]: any } = {
       attributes,
       backend: 'webview-html5',
@@ -166,6 +167,9 @@ export class AsciidocParser {
       sourcemap: true,
       ...(baseDir && { base_dir: baseDir }),
     }
+    if (templateDirs.length !== 0) {
+      options.template_dirs = templateDirs
+    }
 
     try {
       const document = processor.load(text, options)
@@ -261,6 +265,15 @@ export class AsciidocParser {
       : documentPath
   }
 
+  /**
+   * Get user defined template directories from configuration.
+   * @private
+   */
+  private getTemplateDirs () {
+    const templatesDir = vscode.workspace.getConfiguration('asciidoc.preview', null).get<string[]>('templates', [])
+    return templatesDir
+  }
+
   private async confirmAsciidoctorExtensionsTrusted (): Promise<boolean> {
     if (!this.isAsciidoctorExtensionsRegistrationEnabled()) {
       return false

src/asciidoctorWebViewConverter.ts

@@ -88,6 +88,7 @@ export class AsciidoctorWebViewConverter {
   config: AsciidocPreviewConfiguration
   initialData: { [key: string]: any }
   state: object
+  backendTraits: { supports_templates: boolean }
 
   constructor (
     private readonly textDocument: SkinnyTextDocument,
@@ -116,6 +117,9 @@ export class AsciidoctorWebViewConverter {
       disableSecurityWarnings: cspArbiter.shouldDisableSecurityWarnings(),
     }
     this.state = state || {}
+    this.backendTraits = {
+      supports_templates: true,
+    }
   }
 
   /**

src/features/previewConfig.ts

@@ -24,6 +24,7 @@ export class AsciidocPreviewConfiguration {
   public readonly refreshInterval: number
   public readonly useEditorStylesheet: boolean
   public readonly previewStyle: string
+  public readonly previewTemplates: string[]
 
   private constructor (resource: vscode.Uri) {
     const editorConfig = vscode.workspace.getConfiguration('editor', resource)
@@ -50,6 +51,7 @@ export class AsciidocPreviewConfiguration {
     this.styles = asciidocConfig.get<string[]>('styles', []) // REMIND: unused, we should either use it or remove it!
     this.useEditorStylesheet = asciidocConfig.get<boolean>('preview.useEditorStyle', false)
     this.previewStyle = asciidocConfig.get<string>('preview.style', '')
+    this.previewTemplates = asciidocConfig.get<string[]>('preview.templates', [])
     this.refreshInterval = Math.max(0.6, +asciidocConfig.get<number>('preview.refreshInterval', NaN))
   }