Skip to content

Commit ab1dc79

Browse files
YoshihideShiraiggrossetie
YoshihideShirai
and
ggrossetie
authored
allow to register custom Asciidoctor.js extensions (#569)
Co-authored-by: Guillaume Grossetie <[email protected]>
1 parent b5b4fbe commit ab1dc79

11 files changed

+308
-50
lines changed

‎README.md

+62-24
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ An extension that provides live preview, syntax highlighting and snippets for th
2323
- [Snippets](#snippets)
2424
- [Identifying the VS Code Environment](#identifying-the-vs-code-environment)
2525
- [Diagram Integration](#diagram-integration)
26+
- [Use Asciidoctor.js extensions](#use-asciidoctorjs-extensions)
2627
- [User Settings](#user-settings)
2728
- [Visual Studio Code for the Web](#visual-studio-code-for-the-web)
2829
- [Build and Install from Source](#build-and-install-from-source)
@@ -146,35 +147,73 @@ This will store images by default in your document folder, however you may also
146147
:imagesdir: media
147148
```
148149

150+
### Use Asciidoctor.js extensions
151+
152+
When using the preview, the VS code extension can load and register Asciidoctor.js extensions.
153+
154+
By convention, extensions must be located in `.asciidoctor/lib` (at the root of your workspace).
155+
The VS code extension will recursively load all files with the extension `.js` as Asciidoctor.js extensions.
156+
For instance, the following files will be loaded: `.asciidoctor/lib/emoji.js`, `.asciidoctor/lib/emoji/index.js` and `.asciidoctor/lib/foo/bar/baz.js`.
157+
158+
In order to use an Asciidoctor.js extension, you should enable the feature by checking "Enable Asciidoctor.js extensions registration" in the extension settings.
159+
The first time, you will also need to confirm that you trust the authors of the Asciidoctor.js extensions located in _.asciidoctor/lib_.
160+
161+
![Asciidoctor.js extensions trust confirmation message](images/asciidoctor-vscode-trust-exts.png)
162+
163+
**❗ Important:** This feature will execute JavaScript code and should not be enabled if you don't fully trust the authors of the Asciidoctor.js extensions.
164+
165+
**💡 Tip:** You can always update the trust mode using the command "Manage Asciidoctor.js Extensions Trust Mode".
166+
167+
You can create a new extension by creating a JavaScript file in the `.asciidoctor/lib` directory or use an existing one.
168+
Here's an exemple on how to use the [asciidoctor-emoji](https://github.com/mogztter/asciidoctor-emoji) extension:
169+
170+
1. Install the npm package in the workspace directory:
171+
172+
```shell
173+
npm i asciidoctor-emoji
174+
```
175+
176+
2. Create a file a JavaScript file in _.asciidoctor/lib_ with the following content:
177+
178+
```javascript
179+
module.exports = require('asciidoctor-emoji')
180+
```
181+
182+
3. Enjoy :tada:
183+
184+
![Asciidoctor.js Emoji extension enabled!](images/asciidoctor-vscode-emoji-ext.png)
185+
186+
149187
## User Settings
150188

151189
This extension is controlled by a multitude of user settings.
152190

153191
The following list contains all the options and their default value.
154192

155-
| Option: Default value | Description |
156-
| :--- | :--- |
157-
| `asciidoc.asciidoctorpdf_command: "asciidoctor-pdf"` | The path or command invoked when using Asciidoctor PDF for the _Export as PDF_ function. |
158-
| `asciidoc.forceUnixStyleSeparator: true` | Force set the file separator style to unix style. If set false, separator style will follow the system style. |
159-
| `asciidoc.preview.style: ""` | The local path to a CSS style sheet to use in the AsciiDoc preview. Relative paths are interpreted relative to the workspace folder. If no workspace is open the document path. |
160-
| `asciidoc.preview.attributes: {}` | Set attributes to be used in the preview. Attributes need to be written as an object of type {string: string} |
161-
| `asciidoc.preview.breaks: false` | Sets how line-breaks are rendered in the AsciiDoc preview. Setting it to 'true' creates a `<br>` for every newline. |
162-
| `asciidoc.preview.doubleClickToSwitchToEditor: true` | Double click in the AsciiDoc preview to switch to the editor. |
163-
| `asciidoc.preview.fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', 'HelveticaNeue-Light', 'Ubuntu', 'Droid Sans', sans-serif"` | Controls the font family used in the AsciiDoc preview. |
164-
| `asciidoc.preview.fontSize: 14` | Controls the font size in pixels used in the AsciiDoc preview. |
165-
| `asciidoc.preview.lineHeight: 1.6` | Controls the line height used in the AsciiDoc preview. This number is relative to the font size. |
166-
| `asciidoc.preview.linkify: true` | Enable or disable conversion of URL-like text to links in the AsciiDoc preview. |
167-
| `asciidoc.preview.markEditorSelection: true` | Mark the current editor selection in the AsciiDoc preview. |
168-
| `asciidoc.preview.openAsciiDocLinks: "inPreview"` | How should clicking on links to AsciiDoc files be handled in the preview.<br/>"inPreview" Try to open links in the the AsciiDoc preview<br/>"inEditor" Try to open links in the the editor |
169-
| `asciidoc.preview.scrollEditorWithPreview: true` | When an AsciiDoc preview is scrolled, update the view of the editor. |
170-
| `asciidoc.preview.scrollPreviewWithEditor: true` | When an AsciiDoc editor is scrolled, update the view of the preview. |
171-
| `asciidoc.preview.scrollPreviewWithEditorSelection: true` | [Deprecated] Scrolls the AsciiDoc preview to reveal the currently selected line from the editor.<br/>This setting has been replaced by 'asciidoc.preview.scrollPreviewWithEditor' and no longer has any effect. |
172-
| `asciidoc.preview.refreshInterval: 2000` | Interval (in miliseconds) between preview refreshes (when the document is changed), 0 means refresh only on save |
173-
| `asciidoc.preview.useEditorStyle: true` | Use editor style instead of default asciidoctor.css |
174-
| `asciidoc.previewFrontMatter: "hide"` | Sets how YAML front matter should be rendered in the AsciiDoc preview. "hide" removes the front matter. Otherwise, the front matter is treated as AsciiDoc content. |
175-
| `asciidoc.trace: "off"` | Enable debug logging for the AsciiDoc extension. |
176-
| `asciidoc.use_asciidoctorpdf: false` | Use Asciidoctor PDF instead of the integrated renderer for the _Export as PDF_ command. |
177-
| `asciidoc.use_kroki: false` | Enable kroki integration to generate diagrams. |
193+
| Option: Default value | Description |
194+
|:-------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
195+
| `asciidoc.asciidoctorpdf_command: "asciidoctor-pdf"` | The path or command invoked when using Asciidoctor PDF for the _Export as PDF_ function. |
196+
| `asciidoc.forceUnixStyleSeparator: true` | Force set the file separator style to unix style. If set false, separator style will follow the system style. |
197+
| `asciidoc.preview.style: ""` | The local path to a CSS style sheet to use in the AsciiDoc preview. Relative paths are interpreted relative to the workspace folder. If no workspace is open the document path. |
198+
| `asciidoc.preview.attributes: {}` | Set attributes to be used in the preview. Attributes need to be written as an object of type {string: string} |
199+
| `asciidoc.preview.breaks: false` | Sets how line-breaks are rendered in the AsciiDoc preview. Setting it to 'true' creates a `<br>` for every newline. |
200+
| `asciidoc.preview.doubleClickToSwitchToEditor: true` | Double click in the AsciiDoc preview to switch to the editor. |
201+
| `asciidoc.preview.fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', 'HelveticaNeue-Light', 'Ubuntu', 'Droid Sans', sans-serif"` | Controls the font family used in the AsciiDoc preview. |
202+
| `asciidoc.preview.fontSize: 14` | Controls the font size in pixels used in the AsciiDoc preview. |
203+
| `asciidoc.preview.lineHeight: 1.6` | Controls the line height used in the AsciiDoc preview. This number is relative to the font size. |
204+
| `asciidoc.preview.linkify: true` | Enable or disable conversion of URL-like text to links in the AsciiDoc preview. |
205+
| `asciidoc.preview.markEditorSelection: true` | Mark the current editor selection in the AsciiDoc preview. |
206+
| `asciidoc.preview.openAsciiDocLinks: "inPreview"` | How should clicking on links to AsciiDoc files be handled in the preview.<br/>"inPreview" Try to open links in the the AsciiDoc preview<br/>"inEditor" Try to open links in the the editor |
207+
| `asciidoc.preview.scrollEditorWithPreview: true` | When an AsciiDoc preview is scrolled, update the view of the editor. |
208+
| `asciidoc.preview.scrollPreviewWithEditor: true` | When an AsciiDoc editor is scrolled, update the view of the preview. |
209+
| `asciidoc.preview.scrollPreviewWithEditorSelection: true` | [Deprecated] Scrolls the AsciiDoc preview to reveal the currently selected line from the editor.<br/>This setting has been replaced by 'asciidoc.preview.scrollPreviewWithEditor' and no longer has any effect. |
210+
| `asciidoc.preview.refreshInterval: 2000` | Interval (in miliseconds) between preview refreshes (when the document is changed), 0 means refresh only on save |
211+
| `asciidoc.preview.useEditorStyle: true` | Use editor style instead of default asciidoctor.css |
212+
| `asciidoc.previewFrontMatter: "hide"` | Sets how YAML front matter should be rendered in the AsciiDoc preview. "hide" removes the front matter. Otherwise, the front matter is treated as AsciiDoc content. |
213+
| `asciidoc.trace: "off"` | Enable debug logging for the AsciiDoc extension. |
214+
| `asciidoc.use_asciidoctorpdf: false` | Use Asciidoctor PDF instead of the integrated renderer for the _Export as PDF_ command. |
215+
| `asciidoc.use_kroki: false` | Enable kroki integration to generate diagrams. |
216+
| `asciidoc.registerAsciidoctorExtensions: false` | Enable Asciidoctor.js extensions registration. |
178217

179218
## Build and Install from Source
180219

@@ -188,7 +227,6 @@ npm run package
188227
code --install-extension *.vsix
189228
```
190229
191-
192230
## Issues
193231
194232
If you encounter any problems with the extension and cannot find the solution yourself, please open an issue in the dedicated GitHub page: [asciidoctor-vscode/issues](https://github.com/asciidoctor/asciidoctor-vscode/issues).

‎images/asciidoctor-vscode-emoji-ext.png

13.7 KB
Loading

‎images/asciidoctor-vscode-trust-exts.png

15.3 KB
Loading

‎package.json

+20
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
"onCommand:asciidoc.showLockedPreviewToSide",
4040
"onCommand:asciidoc.showSource",
4141
"onCommand:asciidoc.showPreviewSecuritySelector",
42+
"onCommand:asciidoc.showAsciidoctorExtensionsTrustModeSelector",
4243
"onWebviewPanel:asciidoc.preview"
4344
],
4445
"contributes": {
@@ -110,6 +111,11 @@
110111
"title": "%asciidoc.showPreviewSecuritySelector.title%",
111112
"category": "AsciiDoc"
112113
},
114+
{
115+
"command": "asciidoc.showAsciidoctorExtensionsTrustModeSelector",
116+
"title": "%asciidoc.showAsciidoctorExtensionsTrustModeSelector.title%",
117+
"category": "AsciiDoc"
118+
},
113119
{
114120
"command": "asciidoc.preview.refresh",
115121
"title": "%asciidoc.preview.refresh.title%",
@@ -160,6 +166,11 @@
160166
"command": "asciidoc.showPreviewSecuritySelector",
161167
"when": "asciidocPreviewFocus",
162168
"group": "1_asciidoc"
169+
},
170+
{
171+
"command": "asciidoc.showAsciidoctorExtensionsTrustModeSelector",
172+
"when": "asciidocPreviewFocus",
173+
"group": "1_asciidoc"
163174
}
164175
],
165176
"explorer/context": [
@@ -217,6 +228,10 @@
217228
"command": "asciidoc.showPreviewSecuritySelector",
218229
"when": "editorLangId == asciidoc || asciidocPreviewFocus"
219230
},
231+
{
232+
"command": "asciidoc.showAsciidoctorExtensionsTrustModeSelector",
233+
"when": "editorLangId == asciidoc || asciidocPreviewFocus"
234+
},
220235
{
221236
"command": "asciidoc.preview.toggleLock",
222237
"when": "asciidocPreviewFocus"
@@ -387,6 +402,11 @@
387402
"default": false,
388403
"description": "%asciidoc.use_kroki.desc%"
389404
},
405+
"asciidoc.registerAsciidoctorExtensions": {
406+
"type": "boolean",
407+
"default": false,
408+
"description": "%asciidoc.registerAsciidoctorExtensions.desc%"
409+
},
390410
"asciidoc.wkhtmltopdf_path": {
391411
"type": "string",
392412
"default": "",

‎package.nls.json

+3-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,8 @@
1111
"asciidoc.saveHTML.title": "Save HTML document",
1212
"asciidoc.saveDocbook.title": "Save to DocBook",
1313
"asciidoc.showLockedPreviewToSide.title": "Open Locked Preview to the Side",
14-
"asciidoc.showPreviewSecuritySelector.title": "Change Preview Security Settings",
14+
"asciidoc.showPreviewSecuritySelector.title": "Manage Preview Security Settings",
15+
"asciidoc.showAsciidoctorExtensionsTrustModeSelector.title": "Manage Asciidoctor.js Extensions Trust Mode",
1516
"asciidoc.showSource.title": "Show Source",
1617

1718
"asciidoc.asciidoctorpdf_command.desc": "Full path for the asciidoctor binary/executable",
@@ -34,6 +35,7 @@
3435
"asciidoc.trace.desc": "Enable debug logging for the AsciiDoc extension.",
3536
"asciidoc.use_asciidoctorpdf.desc": "Use asciidoctor-pdf instead of the integrated renderer",
3637
"asciidoc.use_kroki.desc": "Enable kroki integration to generate diagrams.",
38+
"asciidoc.registerAsciidoctorExtensions.desc": "Enable Asciidoctor.js extensions registration.",
3739
"asciidoc.wkhtmltopdf_path.desc": "Full path for the wkhtmltopdf binary/executable",
3840
"asciidoc.forceUnixStyleSeparator.desc": "Force set the file separator style to unix style. If set false, separator style will follow the system style.",
3941
"asciidoc.preview.openAsciiDocLinks.desc": "How should clicking on links to AsciiDoc files be handled in the preview.",

0 commit comments

Comments
 (0)