|
|
:imagesdir: ../images
|
|
|
:toc:
|
|
|
:icons: font
|
|
|
|
|
|
== Recommended Extensions
|
|
|
|
... | ... | @@ -74,33 +75,39 @@ image::vscode_command-palette.png[] |
|
|
|
|
|
image::vscode_activity-bar.png[]
|
|
|
|
|
|
== Adding VSCode Preview support for PlantUML
|
|
|
Credit to https://blog.anoff.io/2019-05-08-asciidoc-plantuml-vscode/
|
|
|
== Adding VSCode support for diagrams (including preview)
|
|
|
|
|
|
[NOTE]
|
|
|
====
|
|
|
This requires a PlantUML server. There are multiple options:
|
|
|
The kroki extension supports a wide range of diagrams from BPMN to Graphviz to PlantUML and Vega graphs using kroki and asciidoctor-kroki.
|
|
|
|
|
|
. use the public plantuml.com/plantuml server
|
|
|
. deploy your own plantuml-server
|
|
|
. run plantuml/plantuml-server docker container on your local machine
|
|
|
====
|
|
|
You can see the full range on the https://kroki.io[kroki website].
|
|
|
|
|
|
This requires a diagram server. There are multiple options:
|
|
|
|
|
|
. use the public kroki.io server
|
|
|
. deploy your own server
|
|
|
. https://docs.kroki.io/kroki/setup/install/[run a kroki docker container] on your local machine
|
|
|
|
|
|
We will go with option 1
|
|
|
|
|
|
WARNING: This is a potential security risk as the rendered images are served via http, ASAM assumes no liability for taking this route.
|
|
|
|
|
|
The option we will use for this feature is asciidoc.preview.attributes that allows you to set arbitrary AsciiDoc attributes. These attributes will be injected into the preview. You could also set the attribute manually on each file but that is really something you do not want to do for generic configs like a server URL. Build systems in the AsciiDoc ecosystem like Antora allow you to set attributes during the build process (see this example), so having a local editor that also injects these attributes is super handy.
|
|
|
WARNING: This extension will send graph information to https://kroki.io. If this is an issue it is also possible to use your own kroki instance (see https://docs.kroki.io/kroki/setup/install/[here for more information]).
|
|
|
|
|
|
To enable diagram support, set the use_kroki parameter in your User Settings to true.
|
|
|
|
|
|
image::enable_kroki.gif[]
|
|
|
|
|
|
To cache and save diagrams locally set the kroki-fetch-diagram attribute in your document header:
|
|
|
|
|
|
Under the hood the AsciiDoc VS Code extension relies on the javascript port of asciidoctor and the asciidoctor-plantuml.js extension. This extension needs the :plantuml-server-url: attribute to be set in the AsciiDoc document to become active and parse PlantUML blocks.
|
|
|
= My Amazing Document
|
|
|
:kroki-fetch-diagram:
|
|
|
This will store images by default in your document folder, however you may also set imagesdir to store them elsewhere:
|
|
|
|
|
|
So all you need to do in VS Code is to hop into your user settings and add the following entry
|
|
|
= My Amazing Document
|
|
|
:kroki-fetch-diagram:
|
|
|
:imagesdir: media
|
|
|
|
|
|
"asciidoc.preview.attributes": {
|
|
|
"plantuml-server-url": "http://plantuml.com/plantuml"
|
|
|
}
|
|
|
|
|
|
The PlantUML images are served over http:// and you must allow your preview to include data from unsafe sources. To do this open your command palette (⌘+P, ctrl+P) and enter asciidoc preview security and choose Allow insecure content. In case you are running a local PlantUML server you may choose Allow insecure local content.
|
|
|
The images are served over http:// and you must allow your preview to include data from unsafe sources. To do this open your command palette (ctrl+shift+P) and enter ``asciidoc preview security`` and choose ``Allow insecure content``.
|
|
|
|
|
|
.opening asciidoc preview security settings
|
|
|
image::plantuml_1.png[]
|
... | ... | |