Features

The main feature is viewing AsciiDoc as HTML5 directly in the browser. Other features cover where those AsciiDoc files are located, and how they are rendered.

You can exercise these features by using the Quickstart page.

View AsciiDoc as HTML5

The screen capture below shows raw AsciiDoc on the left, and rendered HTML5 on the right.

If the extension is inactive, you’ll see the raw AsciiDoc. If it is active, you’ll see the rendered HTML5.

Reproduce this example yourself by following the instructions in the Quickstart page.

Screen capture of two screens, showing raw AsciiDoc and rendered as HTML5

Auto reload

If the content of the page is changed, the rendered view is automatically refreshed.

This means that if you edit the viewed AsciiDoc and save, the rendered view will change.

See Poll for Changes on the options page.

Use AsciiDoc attributes

You can set AsciiDoc attributes in the Asciidoctor Browser Extension to control how your AsciiDoc document is rendered to HTML, without affecting the original document.

The final view is determined by attributes and settings in the:

The attribute settings are applied in the above order of precedence, with query parameters being applied last.

URL query parameters

You may use URL query parameters to change how the extension previews AsciiDoc. You can set:

  • attribute values with ?<attribute-name>=<value>

  • stylesheet used with ?stylesheet=<stylesheet name>

Where to put the query parameters

Query parameters are indicated by the first ? character in the URL and are terminated by the character # or the end of the URL.

If setting attributes or the stylesheet via the URL is not working, check that the query parameters are before any # character in the URL.

Add the first query parameter (?)

For example, to reduce the depth of section levels that are displayed in the table of contents to one, add ?toclevels=1 to the URL (after the document name, and before any # character):

URL query parameters
https://example.com/page.adoc?toclevels=1

Add more query parameters (&)

To add one more parameter, add an ampersand (&) to the end of the last query parameter, followed by the next attribute setting.

It will look like this:

URL query parameters
https://example.com/page.adoc?toclevels=1&stylesheet=maker

Query parameters example

You have a document ex-query.adoc that uses two attributes {first} and {last} to say "Hello {first} {last}!" in the document title.

ex-query.adoc
= Hello {first} {last}!

Query parameters example
Download the above document from ex-query.adoc

Then, to send a first and last name to the document via the URL, you would add ?first=Irma&last=Writer to the URL directly after the ex-query.adoc and before any # character.

URL query parameters
file:///C:/Users/User/Documents/ex-query.adoc?first=Irma&last=Writer

You should see the following result:

Hello Irma Writer!

Query parameters example

Change themes and stylesheets

Change the stylesheet, CSS, or both, that are used to render HTML5 from the AsciiDoc. For example, you may prefer a darker or a more compact presentation style.

The Theme/Stylesheet can be changed for:

View AsciiDoc files locally and remote

View AsciiDoc files from different locations.

The extension allows you to view AsciiDoc files from your local file system and from the Web:

  • Local URLs start with file://

  • Remote URLs start with https:// (this includes developer platforms such as GitHub or GitLab)

    Use Raw Mode to view AsciiDoc files using the Asciidoctor Browser Extension and not native rendering provided by developer platforms.
Your settings are applied on both local and remote files.

Make use of diagrams as text

Using diagrams as text within AsciiDoc allows you to create visual diagrams using plain text, providing a cohesive and unified approach to content creation.

three step process
Figure 1. Three-step process diagram

With diagrams as text, you can do the same with diagrams. There are many types of diagrams that can be generated this way from basic block diagrams to complex technical architecture diagrams including data-science visualizations, entity relationships, and more.

When the Option: Diagrams Extension is enabled via the Extension Options, the Asciidoctor Browser Extension converts diagrams from text to image using a local or remote Kroki diagram server, and shows them as if they were local or remote image files in the HTML.

Learn more on the Option: Diagrams Extension page.

Markdown friendly

AsciiDoc is similar enough to Markdown that often you can write simple Markdown in your AsciiDoc document and it will just work. This may save you time in the following situations:

  • Writing simple notes

  • Converting files from Markdown to AsciiDoc gradually.

Learn more about these two text markup formats at: