User guide for the ST4-Asciidoctor package.

Introduction

The goal of this guide is to document the various features of the ST4-Asciidoctor package, serving as a reference guide, and at the same time try to illustrate how to maximize the benefits of the package by providing practical editing tips via usage guidelines.

To simplify learning for AsciiDoc or Sublime Text newbies, some technical terms contain links to their official documentation, so that they might be easily looked up for more information.

The Manual is still a work-in-progress in its early stages.

You’re advised to consult this guide from time to time because while the package is in Alpha stage it’s subject to features changes, so you might discover that after an update the package is not working as before. Once the package will reach v1.0.0, braking changes will occur rarely.

Accessing the User Guide

You can quickly access this online user guide from within Sublime Text via the menu:

  • Preferences  Package Settings  Asciidoctor  User Guide

Although access to the guide requires an Internet connection, the advantage of an online guide is that you’ll always have access to the latest documentation, since this guide is often updated between package releases.

Package Features

The list of editing features natively supported by the package.

Associated File Extensions

The following file extensions are automatically recognized as AsciiDoc files:

  • .adoc

  • .asc

  • .asciidoc

Snippets

The following table lists the package snippets and their features.

Name Trigger S W Fields

Button

btn Tab

No

Comment Block

// Tab

Yes

78

Document Title

h0 Tab

No

Example Block

n/a

Yes

78

Title

Footnote

fn Tab

Yes

Footnote Reference

fnr Tab

Yes

ID

Image (block)

img Tab

No

Title, path, alt text, width, height

Keyboard Shortcut

kbd Tab

No

Listing Block

-- Tab

Yes

78

Lang

Passthrough Block

n/a

Yes

78

Title

Quoted Block

__ Tab or "" Tab

Yes

78

Attribution, Title

Section Titles 1–5

h1 Tab …​ h5 Tab

No

Sidebar Block

sbar Tab

Yes

78

Table

|= Tab

No

78

Caption, cols, opts

The meaning of the table columns are:

Name

The exact name of the snippet, for invoking it via the Command Palette.
Trigger

The snippet text trigger (if any).
S [Selection]

whether the snippets preserve or not the current selection (if any).
W [Width]

The width of elements which can be optionally represented my multiple characters, e.g. block delimiters. In most cases, block delimiters generated via snippets are extended to 78 characters, for decorative purposes.
Fields

The list of extra supported fields (if any) which the user can navigate through via Tab, usually holding some preset values.

Completions

  • Provides completions for attributes (built-in and locally defined) and cross references (local anchors and titles).

Keymap Details

Comments

Both inline and block comments are support via the default Sublime Text key bindings — usually, Ctrl+Numpad / and Ctrl+Shift+Numpad /, respectively.

Auto-Paired Punctuation

  • Asterisks (strong), underscores (emphasis), backticks (monospaced), English quotation marks, and Czech quotation marks are autopaired and will wrap selected text.

    • If you start an empty pair and hit backspace, both elements are deleted.

    • If you start an empty asterisks pair and hit Space or Tab, the right element is deleted (because you probably wanted to start a list, not a strong text).

Lists and Callouts

  • At the end of a list item (ordered or unordered), pressing Enter will automatically insert the new list item “bullet.”

    • Pressing Enter on the blank list item will remove it.

    • Pressing Tab on the blank list item, or selected item(s), will increase the nesting level and indent it.

    • Pressing Shift + Tab on the blank list item, or selected item(s), will decrease nesting level and unindent it.

  • At the end of a callouts list item, pressing Enter will automatically insert the new list item with an incremented number.

    • Pressing Enter on the blank list item will remove it.

You can disable indentation of list items in your settings file.

Symbols Indexing

This section illustrates how the package handles symbols indexing and the various Goto functionality associated with it:

Local symbols

i.e symbols in the current document — accessible via:

  • Menu: Goto  Goto Symbol…​

  • Keyboard: Ctrl+R/Cmd+R
Global symbols

i.e symbols in the current project — accessible via:

  • Menu: Goto  Goto Symbol in Project…​

  • Keyboard: Ctrl+Shift+R/Cmd+Shift+R

Section Titles

Document and section titles are displayed in both the local and global Goto Symbol lists:

  • In the local symbol list, titles are nicely indented according to hierarchy.

  • In the global symbol list, titles are prefixed with = characters (as in the AsciiDoc source), which allows to quickly filter them out by typing =, as well as providing an easy visual cue to identify them.

Build System

This package defines a build system for AsciiDoc files that targets HTML, EPUB, and DOCX. With the source AsciiDoc file open in the editor, simply press Ctrl+Shift+B to invoke the build system, and then select your target.

Table 1. Targets

Asciidoctor

Generates HTML

Asciidoctor - EPUB

Generates EPUB (via asciidoctor-epub3)

Asciidoctor - DOCX

Generates a Word document (via pandoc)

Or, press Ctrl+B to repeat the build for the last target selected.

In all cases, the generated file will be placed alongside the source file, in the same folder. In the case of a DOCX file, it will be opened automatically using your system’s default program for the DOCX file type.

Build System Requirements

  • For HTML, this assumes that asciidoctor is installed on the system path.

  • For EPUB, this assumes that asciidoctor-epub3 is installed on the system path.

  • For DOCX, this assumes that pandoc is installed on the system path (along with asciidoctor).

There is currently only a Windows implementation for DOCX.

Specifying a reference.docx file for Pandoc

Pandoc has the ability to start with a reference DOCX file that, for example, defines all of the paragraph and character styles you’d like to be included in the target. This build system supports three different ways to specify such a reference docx file for pandoc to use:

  1. If the AsciiDoc source file contains an attribute definition for :pandoc:, :pandoc-ref:, or :pandoc-reference:, and the value of that attribute exists as a file, then it will be used. NOTE: There is nothing special about us using an attribute definition for this. This build system searches the source file directly for the file reference, so we could have buried it in a comment, for example. Using attribute syntax just seemed appropriate. By the time the source file is processed by AsciiDoctor, the :pandoc…​: attribute will just be ignored. Be aware that if there are multiple :pandoc…​: attributes defined in the file, only the last one will be used. Also, this script will only find :pandoc…​: attributes that are in the main source file, not in any included files.

  2. If .\reference.docx exists, it will be used.

  3. If .\.pandoc\reference.docx exists, it will be used.

  4. Otherwise, no reference file will be used.

Usage Tips

You can leave an HMTL file open in your browser while you regenerate it. Then, just refresh the page with F5. For EPUB and DOCX files, however, you must close them before they can be regenerated.

Color Schemes

Using ST4’s Default Color Schemes

ST4 ships with five default colors schemes: “Breakers,” “Celeste,” “Mariana,” “Monokai,” and “Sixteen.”

They all have minimal support for colorizing markup files, in general, but none of them are nuanced in the particulars imparted by our AsciiDoc syntax specification, since our specification did not exist at the time that these schemes were created. Nonetheless, a main objective of our syntax specification is to conform to the naming conventions expected by these default color schemes, so that they will continue to provide that minimal, generic support when it comes to AsciiDoc files in particular.

Basic Scope Names

Here is a cumulative list of the scope names that are recognized by the default color schemes; however, not all of these scopes are recognized by all of the schemes. For example, all of them colorize comment, but not all of them colorize the corresponding punctuation.definition.comment (by the choice of that color scheme’s designer).

For another example, all of them colorize invalid.illegal and invalid.deprecated, but they do it differently. Some will colorize the two specifically by name, while others first colorize invalid in general, and then specify a different color for invalid.deprecated qualifier in particular — which, by the way, is the recommended way of doing it.

Anyone who sets out to create a fresh color scheme that does support the AsciiDoc nuances, should also ensure that the basics are covered first.

To understand the semantics of these scope names, see: https://www.sublimetext.com/docs/scope_naming.html

comment:

(comment has no qualifiers.)

constant:

  • constant.character

  • constant.character.escape

  • constant.language

  • constant.numeric

  • constant.numeric.line-number.find-in-files

  • constant.numeric.line-number.match

  • constant.other

  • constant.other.color

  • constant.other.language-name

diff:

  • diff.deleted

  • diff.deleted.char

  • diff.inserted

  • diff.inserted.char

entity:

  • entity.name

  • entity.name.filename

  • entity.name.function

  • entity.name.label

  • entity.name.section

  • entity.name.tag

  • entity.name.tag.yaml

  • entity.other.attribute-name

  • entity.other.attribute-name.id

  • entity.other.inherited-class

  • entity.other.pseudo-class

invalid:

  • invalid.deprecated

  • invalid.illegal

keyword:

  • keyword.declaration

  • keyword.operator

  • keyword.operator.word

markup:

  • markup.bold

  • markup.changed

  • markup.deleted

  • markup.heading

  • markup.heading.1

  • markup.heading.2

  • markup.inserted

  • markup.italic

  • markup.list

  • markup.list.numbered

  • markup.list.numbered.bullet

  • markup.list.unnumbered.bullet

  • markup.quote

  • markup.raw

  • markup.raw.inline

  • markup.underline

  • markup.underline.link

match:

(match has no qualifiers.)

message:

  • message.error

meta:

  • meta.diff

  • meta.diff.header

  • meta.function-call

  • meta.structure.dictionary.json

  • meta.table.header

punctuation:

  • punctuation.accessor

  • punctuation.definition

  • punctuation.definition.annotation

  • punctuation.definition.blockquote

  • punctuation.definition.bold

  • punctuation.definition.comment

  • punctuation.definition.constant

  • punctuation.definition.heading

  • punctuation.definition.image

  • punctuation.definition.italic

  • punctuation.definition.link

  • punctuation.definition.list_item

  • punctuation.definition.metadata

  • punctuation.definition.numeric.base

  • punctuation.definition.raw

  • punctuation.definition.string

  • punctuation.definition.thematic-break

  • punctuation.section

  • punctuation.section.embedded

  • punctuation.section.table-header

  • punctuation.separator

  • punctuation.separator.table-cell

  • punctuation.terminator

source:

  • source.c

  • source.c++

  • source.css

  • source.objc

  • source.objc++

  • source.ruby

  • source.yaml

storage:

  • storage.type

  • storage.type.numeric

string:

  • string.other.link

  • string.quoted.double.json

  • string.regexp

  • string.unquoted

  • string.unquoted.yaml

support:

  • support.class

  • support.class.builtin

  • support.class.dollar.only.js

  • support.constant

  • support.function

  • support.function.builtin

  • support.macro

  • support.other.variable

  • support.type

  • support.type.property-name

  • support.type.sys-types

  • support.type.vendor-prefix

text:

(text has no qualifiers.)

variable:

  • variable.annotation

  • variable.function

  • variable.interpolation

  • variable.language

  • variable.member

  • variable.other.dollar.only.js

  • variable.other.object.dollar.only.js

  • variable.parameter

  • variable.type.dollar.only.js

AsciiDoc-Specific Color Schemes

This package ships with a dedicated color scheme (“AsciiDoc Dark”) which takes full advantage of this package’s AsciiDoc syntax specification. For example, the “Molokai”, “Breakers”, and “Celeste” color schemes that ship with ST4 do not bother to highlight the list bullets, nor the fences around tables, nor any of the markers that start and end various blocks (examples, sidebar, etc.).

To enable the “AsciiDoc Dark” scheme, or pick any other color scheme of your choice, simply pull down the “Preferences” menu and use “Select Color Scheme…​”.

Since this package is still very much under development, it is important that collaborators use an AsciiDoc-specific color scheme in order to appreciate/experience/test the syntax highlighting nuances. Many elements of the AsciiDoc syntax rely on (fine-grained) scope names which are peculiar to AsciiDoc, and very unlikely to be covered by general-purpose color schemes designed for programming languages or lightweight markup syntaxes (like Markdown, reST, etc.).