How to Set Custom Attributes in the Asciidoctor.js Live Preview Extension

Whether I’ve been updating my Zend Expressive (now Mezzio) book or doing technical writing client work, I write and edit a lot of AsciiDoc content. And while I can generally know if I’ve made a mistake in the content that I’ve written, just by reading it, I won’t always know if it renders correctly, or quite as I’d like.

So, to preview AsciiDoc content, I use the Asciidoctor.js Live Preview extension (in both Firefox and Chrome/Chromium). I added the extension to my workflow some months ago, as my editor of choice, VIM (MacVIM on macOS and plain VIM on Linux), unlike other editors such as SublimeText and Atom, can’t integrate preview support natively.

If this is your first time hearing about the extension, after installing and enabling it, all you need to do is open an AsciiDoc file, and it renders as HTML, using one of several custom themes. It’s a speedy way of knowing how your content will, approximately, look later, when generated.

Up until recently, I only used it to review text and didn’t worry about other facets, such as included images and example files. This was mainly because the AsciiDoc content that I wrote was part of an Antora project. Given that, when I was happy enough with the content, I’d typically use yarn antora to generate an up to date version of the documentation and then view the generated documentation.

However, as some documentation projects I’ve been working on have grown ever larger, generating a full set of documentation to view a small change became quite impractical. However, I don’t always write content which is part of an Antora project, so I needed a preview tool to review the content before it was committed to version control.

Given that, I’ve come to rely on the Live Preview extension ever more, to the point that I use it, almost, daily. For example, I write or update some content in VIM and then switch to the tab in Firefox, which previews the content, to see how the document renders.

Because of the increased reliance, I’m now reviewing all content, not just text. As a result, I found that there were little things which, by default, the extension wouldn’t render correctly, such as images and include examples.

To “fix” these “issues”, I started adding custom attributes in the AsciiDoc source files, such as imagesdir, to set the path to the images for that file, and experimental to enable AsciiDoc’s experimental features.

Right from the start, this felt like a hack. As I’m guessing you’ll agree. Yes, I’m somewhat embarrassed at my laziness. :-( To make matters worse, I intermittently committed those attributes to source control.

Long story short, I did what I should have done originally, check the extension’s configuration options to see if it supports setting custom attributes. As you would likely expect, you can set custom attributes in the plugin.

For the remainder of the post, I’m going to step through how to do so. Let’s assume that you want to view images in your content. To do that, you set the imagesdir attribute, so that the plugin knows the image base path. For example, in the image below, you can see that the image is missing, based on the following line AsciiDoc source file:

image::core-component-pimple.png[Pimple, Laminas Mezzio's default Dependency Injection container implementation, align="center"]

Because the imagesdir attribute isn’t set by default, the plugin does not know where to find the image. To set the custom attribute, right-click on Asciidoctor.js Live Preview’s icon in the Firefox toolbar and click “Manage Extension” in the menu that appears.

This takes you to the extension’s configuration settings, putting you on the Details tab by default. Click the Preferences tab, between Details and Permissions, to change to the Preferences tab.

There, in the Asciidoctor options section, you’ll see that the first field is named “Custom attributes”. There, you can enter a series of space-separated, key/value attribute pairs. When set, the attributes are available to any AsciiDoc content which the extension renders from then on.

Assuming that your images are stored in /opt/my-project/images/, then add imagesdir=/opt/my-project/images/ in the field. The changes are saved automatically. Finally, reload the page. As I’ve done so, in the image below, you can see that the previously broken image now renders correctly.

In Summary

The Asciidoctor.js Live Preview extension is an excellent way of previewing AsciiDoc content quickly and effectively, regardless of whether you’re writing a single page, content as part of a larger project, such as a book/e-book, or an Antora-based, technical documentation, project.

It lets you avoid installing extra software unnecessarily, which is excellent if you’re a text editor (VIM) lover like myself or if you want a workflow that requires minimal investment to set up and use.

If you haven’t used it already, I strongly encourage you to do so. If you need any help with it, make sure you raise an issue in the GitHub project, or come hang out in the Asciidoctor forum.