Preview Templates not working

[cunka]

Trying to modify the VSCode Asciidoctor "Preview" through the use of a Nunjuck Template.

There is a Setting in VScode called Asciidoc > Preview:Templates that says if this folder is left empty then templates will be discovered relative to the asciidoc file.

So if I have the nunjucks file and the asciidoc file together it should work.
It doesnt.

If I set up a folder to place the templates and add that path to the Setting in VScode *Asciidoc > Preview:Templates, it still doesnt work.

I have folder in my project called templates.
My setting in VSCode then for *Asciidoc > Preview:Templates I tried:

templates
//templates
.//templates

Nunjucks has been installed in VScode terminal using $ npm i nunjucks

Files are:
paragraph.njk

<p class="paragraph">Brian Did This : {{ node.getContent() | safe }}</p>

test.adoc

= TEST DOCUMENT

Paragraphs don't require any special markup in AsciiDoc.
A paragraph is just one or more lines of consecutive text.

I expected the nunjucks paragraph template to be found and modify the VSCode Asciidoctor "Preview" where a paragraph was used.

[ggrossetie]

Only an absolute path seems to work.
As far as I know, nunjucks won't be available in the VS Code context so only plain JavaScript:

paragraph.js

module.exports = ({ node }) => `<p class="paragraph">Brian did this: ${node.getContent()}</p>`

Settings

C:\path\to\templates

[ggrossetie]

In short:

The setting description is wrong:

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 \\.

I don't think "All \ need to be written as \\." is true.
We should recommend to use forward slash since it supported on Windows and VS Code is using URI.
We should append the workspace directory and the location of the AsciiDoc file if the path is relative.
We should disable the template cache (using template_cache) otherwise the user needs to restart the VS Code extension when a changes is made on a template file.

We should mention that only plain JavaScript is supported.
It's possible to support additional template engine but we will need to include them in the VS Code extension bundle (thus increasing the size of the bundle)

[cunka]

Thanks I got this to work with your help. (Javascript "paragraph" you supplied)
Out of the box in VSCode supporting Javascript only is fine.

There is a few caveats we may need to document with all this though..

Firstly, in Settings in VSCode, there is the "User" and "Workspace" settings.
I was modifying the User settings and it wasn't working. Only works with the "Workspace" settings.

As you mentioned, doing the \\ doesnt work, it has to be \.
The reason is the settings.json file makes the paths \\. If you make it \\ the json file ends up putting in \\\\.

[ggrossetie]

As you mentioned, doing the \ doesnt work, it has to be .
The reason is the settings.json file makes the paths \. If you make it \ the json file ends up putting in \\.

\ character must be escaped in a JSON file (i.e., general rule). I think we should recommend to use forward slash / (instead of stating that \ must be escaped if the user is editing the settings.json directly)

Firstly, in Settings in VSCode, there is the "User" and "Workspace" settings.
I was modifying the User settings and it wasn't working. Only works with the "Workspace" settings.

I don't think this is intended. I will have a look.

[lask79]

I also can see that only absolute paths are working. Isn't there a way to implement a simple way that the configured relative paths can be configured to use ${workspaceFolder}/templates or even better if it can be defined that the vscode extension automatically finds the templates under .asciidoctor/templates?

It is really annoying to manually set the templates path for each developer after checking out the repository and I think that could be easily improved.

[ggrossetie]

Isn't there a way to implement a simple way that the configured relative paths can be configured to use ${workspaceFolder}/templates

We could support interpolation (i.e., replace ${workspaceFolder} by the actual workspace folder path). It might be better than trying to resolve the relative path since it's unclear if the path is relative to the workspace folder (root) or to the AsciiDoc file. Maybe relative paths should be resolved relative to the AsciiDoc file and if you want to resolve it relative to the workspace folder then you need to use ${workspaceFolder} ?

Alternatively, we could use dot (.), tilde (~), or tilde plus (~+) similarly to what https://gitlab.com/antora/expand-path-helper#user-content-usage does.

• dot (.) relative to AsciiDoc file
• tilde (~) relative to $HOME
• tilde plus (~+) relative to workspace folder

@mojavelinux thoughts?

[lask79]

Providing a convention like mentioned here #843, might even be the easier solution. When already starting with conventions for extensions, why not doing the same for templates?