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

The Asciidoctor.js Live Preview extension allows custom AsciiDoc attributes to be set using file query strings. In this post, I show you how to do so, along with how to use it in tandem with the extension’s configuration UI.

Last week, I showed how to set custom AsciiDoc attributes in the Asciidoctor.js Live Preview extension using the extension’s configuration UI. In this week’s post, I’m following up that post by showing how to set custom attributes using file query strings.

Why didn’t I do it last week, you may be asking. Well, it wasn’t something that I was aware of at the time. After I shared the post in the Asciidoctor Gitter forum, the project lead (Dan Allen) told me that custom attributes can also be set using query string parameters.

If you’re not familiar with query strings, it’s the part of a URI where you can set key/value parameters. Take the following URL as an example.

In the example URL above, two parameters (date and mode) are set in the query string (date=2020-04-01&mode=test). Date is set to 2020-04-01. Mode is set to test.

Why Set Custom AsciiDoc Attributes Using Query Strings?

Well, firstly, as I covered in last week’s post, custom AsciiDoc attributes set using the configuration UI apply to every AsciiDoc file that is previewed — even if they have no bearing on that file!

Secondly, to change them, you have to open up the Options tab in the configuration UI each time that you want to change them. Sure, it’s only a few mouse clicks away, but unless you keep it open, you have to invest those few mouse clicks every time that you want to update the custom attributes.

Compare this, however, to setting attributes in the query string of the file that you’re currently previewing. When setting attributes this way, the attributes set only apply to the current file. Any AsciiDoc file being previewed in another tab won’t have them set. To set them you only need to change the query string in your browser’s address bar.

Why Not Use Both?

As I write this, I see a pretty satisfying middle ground of using a combination of both approaches. If it makes sense, that is. If there are AsciiDoc attributes globally applicable to all the AsciiDoc files which you might preview, such as the experimental attribute or the images directory, then set them in the extension’s configuration UI.

After that, set page-specific attributes in the browser tab’s query string for that particular file. That way, you only need to set the globally-specific attributes once.

In Summary

This has been a short walkthrough of how to set custom AsciiDoc attributes using file query strings when using the Asciidoctor.js Live Preview extension. Using query strings provides a quick and flexible way of setting custom attributes on a per/page basis. When combined with globally applicable settings in the extension’s configuration UI, it makes previewing content relatively quick and very convenient.

You might also be interested in...

comments powered by Disqus


Docker Essentials. Learn the four essential skills you need to build and deploy applications with Docker! Mezzio Essentials. Learn the fundamentals that you need, to begin building applications with the Mezzio framework today!

Latest YouTube Video

Learn how to write SQL queries in PhpStorm