Edit AsciiDoc files

The extension enhances the editor with AsciiDoc-aware features.

Syntax highlighting

AsciiDoc syntax is highlighted as you type, making documents easier to read and structure.

Document outline and symbols

The structure of your document (sections, blocks) is exposed through the VS Code outline and the Go to Symbol command (Ctrl+Shift+O, Mac: Cmd+Shift+O).

Format text

Toggle bold, italic and monospace with keyboard shortcuts. See Format text.

Snippets

Insert common AsciiDoc constructs in a few keystrokes. See Snippets.

Paste an image

Paste an image straight from the clipboard into your document. See Paste an image.

Resolve attributes on hover

Hover over an attribute reference such as {name} to see the value it resolves to. See Attribute value on hover.

You can also preview your changes live as you edit. See Preview.

Attribute value on hover

When you hover over an attribute reference such as {version}, the extension shows the value the attribute resolves to:

{version} = 2.1.0

If the attribute is not defined, the hover tells you so instead:

{verison} is not set in this document.

This is handy for catching typos in attribute names: a misspelled reference is reported as not set rather than silently rendering as literal text in the preview.

Why the hover sometimes shows nothing or "not set"

The value comes from parsing the document header, so only attributes that Asciidoctor knows about at that point are resolved. Understanding what is included avoids surprises:

The hover resolves these attributes

  • Attributes declared in the document header (before the first blank line following the title)

  • Attributes provided by a .asciidoctorconfig file. See Asciidoctor configuration file.

  • Attributes set through the asciidoc.preview.asciidoctorAttributes setting. See Settings.

  • Intrinsic (built-in) attributes such as docdir, docname or asciidoctor-version

The hover does not resolve these attributes, and reports them as not set

  • Attributes declared in the body of the document, i.e. anywhere after the header

  • A redefinition of an attribute that appears after the header (the header value is shown, not the later one)

  • Attributes contributed by an include::[] directive located in the body

  • Attributes set or unset conditionally (for example inside an ifdef::[] block)

Body-level attributes are only applied by Asciidoctor while it converts a document, and the hover works on the parsed document without converting it (for speed). Resolving those values reliably would require tracking every attribute assignment in document order, which is intentionally out of scope. The preview always renders the fully converted document, so use it when you need the final, position-accurate value.

No hover is shown at all when the reference sits inside a verbatim block (for example a ---- listing or literal block) that does not run the attributes substitution. In that context Asciidoctor keeps {name} as literal text, so displaying a resolved value would be misleading. This matches the behaviour of attribute-reference auto-completion.

Attribute names are case-insensitive, so {Version} and {version} resolve to the same value.