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.
http://example.org/blog/?date=2020-04-01&mode=test
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.
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.
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.
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.
In this post, I step through how to set custom AsciiDoc attributes in the Asciidoctor.js Live Preview Extension for Firefox (and Chromium/Chrome). By doing so, you can preview your content properly and avoid setting attributes directly in your AsciiDoc content and other hacks.
I’ve been reviewing the AsciiDoc plugin for IntelliJ over the last four weeks. In this post, I share everything that I learned.
Whenever you create online documentation, eventually, the structure needs to change; such as a name change, content restructure, or old content is removed. When these times come, it’s important to create redirects to avoid breaking user expectations. In this post, I’m going to step you through how to do so with Antora.
If you need to create and maintain technical writing, there are a large number of solutions that will give you a lot of what you want. However, which one is the best? Today, I’ll show you which one I believe is the best choice.
Please consider buying me a coffee. It really helps me to keep producing new tutorials.
Join the discussion
comments powered by Disqus