Preview AsciiDoc with embedded PlantUML in VS Code
Tags: productivity, tutorial, documentation, webdev
Published: 2019-05-11 16:55:18

---
title: Preview AsciiDoc with embedded PlantUML in VS Code
published: true
description: Configuring VS Code to render PlantUML images with just one line
tags: productivity, tutorial, documentation, webdev
---

> Crosspost from [blog.anoff.io/2019-05-08-asciidoc-plantuml-vscode](https://blog.anoff.io/2019-05-08-asciidoc-plantuml-vscode/)

![logo](https://blog.anoff.io/assets/asciidoc-plantuml/title.png)

This post is for everyone that likes to write AsciiDoc in VS Code but also wants to inline PlantUML diagrams within their docs. In a previous post about [diagrams with PlantUML](https://blog.anoff.io/2018-07-31-diagrams-with-plantuml/) I gave an intro into PlantUML and how to preview images in VS Code. With the latest release of the asciidoctor plugin for VS Code it is possible to easily preview embedded PlantUML images within AsciiDocs.

Follow me on Twitter at [@an0xff](https://twitter.com/an0xff) for future blog updates, not all of them make it to dev.to. Currently I am writing mostly about docs-as-code.

## Prerequisites

You should already have [Visual Studio Code installed](https://code.visualstudio.com/docs/setup/setup-overview) on your machine. At the time of writing this post I am using v1.33.1 on MacOS and also verified the setup on a Windows 10 machine.

For the AsciiDoc preview to work we will use the [AsciiDoc extension](https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode) that you can get by executing

```sh
code --install-extension joaompinto.asciidoctor-vscode
```

> 💡 The feature we are going to use here is rather new and shipped with 2.6.0 of the AsciiDoc plugin.

The third thing you need is a PlantUML server. There are multiple options:

1. use the public [plantuml.com/plantuml](http://plantuml.com/plantuml) server
2. deploy your own java [plantuml-server](https://github.com/plantuml/plantuml-server)
3. run [plantuml/plantuml-server](https://hub.docker.com/r/plantuml/plantuml-server/) docker container on your local machine

For test cases option 1 works fine; even if the server claims it does not store any data I would advise you to host your own server if you are working on anything professionally that is not open source. Setting up a PlantUML server is rather easy if you are familiar with Docker, you can see an example setup in [my blog post from march 2019](https://blog.anoff.io/2019-03-24-self-hosted-gitea-drone/). Finally the third option of running it locally within docker is great if you are on the road or sitting somewhere without WiFi.

This post will use option 1 as it just works out of the box while following these instructions.

## Configuring the extension

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](https://antora.org/) allow you to set attributes during the build process (see [this example](https://github.com/anoff/antora-arc42/blob/master/playbook-remote.yml#L21)), so having a local editor that also injects these attributes is super handy.

Under the hood the AsciiDoc VS Code extension relies on the javascript port of asciidoctor and the [asciidoctor-plantuml.js](https://github.com/eshepelyuk/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.

So all you need to do in VS Code is to hop into your user settings and add the following entry

```javascript
"asciidoc.preview.attributes": {
  "plantuml-server-url": "http://plantuml.com/plantuml"
}
```

> ⚠️ The downside of using the public server is that it does not offer SSL encrypted endpoints and you must weaken your VS Code security settings to preview correctly.

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.

![screeenshot](https://blog.anoff.io/assets/asciidoc-plantuml/cmd1.png)

Figure 1. opening asciidoc preview security settings

![screeenshot](https://blog.anoff.io/assets/asciidoc-plantuml/cmd2.png)

Figure 2. allow insecure content

## Live Preview AsciiDoc with embedded PlantUML

To test it out just create an example file with some PlantUML content.
puml

![plantUML image](https://blog.anoff.io/assets/asciidoc-plantuml/puml.svg)

Figure 3. This image is rendered on the fly

With the attribute set correctly the above code block renders as an image

![preview showing a diagram](https://blog.anoff.io/assets/asciidoc-plantuml/preview-ok.png)

..without the attribute set or issues with the security settings you just see a code block

![preview showing only code](https://blog.anoff.io/assets/asciidoc-plantuml/preview-nok.png)

Hope this post helped you. If you have any questions or know of better/alternative ways leave a comment 👋