Preview

The extension renders a live preview of your document using Asciidoctor.js.

Open the preview

The same commands as the Markdown extension are available:

Toggle Preview — Ctrl+Shift+V (Mac: Cmd+Shift+V)
Open Preview to the Side — Ctrl+K V (Mac: Cmd+K V)

The preview updates automatically as you type. You can also force a refresh with the AsciiDoc: Refresh Preview command.

Control when the preview updates

By default the preview re-renders as you type, throttled by the asciidoc.preview.refreshInterval setting (in milliseconds, 2000 by default).

Set the interval to 0 to turn off live updates entirely:

"asciidoc.preview.refreshInterval": 0

The preview then refreshes only when you ask for it, in one of two ways:

Save (Ctrl+S, Mac: Cmd+S): Re-renders every open preview, keeping its scroll position. Saving an `include::`d file refreshes the preview too — includes are read from disk, so the change must be saved (saving the parent while an include is still unsaved keeps showing the old include).
AsciiDoc: Refresh Preview command: Forces a refresh on demand without saving anything, and fully reloads the preview (styles, theme, webview shell), resetting the scroll position. Use it when an include was changed outside VS Code — no save event fires there — or when you want a clean rebuild.

This is useful for documents with heavy content — for example complex MathJax equations that would otherwise re-typeset and jump around on every keystroke.

AsciiDoc attributes

Set AsciiDoc attributes used to render the preview through the asciidoc.preview.asciidoctorAttributes setting.

Front matter

Files written for static-site generators (Jekyll, Hugo, …) often start with a metadata block delimited by + (TOML) or --- (YAML):

---
title: cool example
layout: post
---
= My Document

body content

By default, Asciidoctor does not treat this block as metadata, so the preview renders it as a stray horizontal rule followed by a paragraph of key: value lines.

To strip the front matter from the preview, set the skip-front-matter attribute through the asciidoc.preview.asciidoctorAttributes setting:

"asciidoc.preview.asciidoctorAttributes": {
  "skip-front-matter": ""
}

The front matter is then consumed and exposed as the front-matter attribute, exactly as with the Asciidoctor --attribute skip-front-matter command-line option.

The attribute must be set through the setting, not in the document header or an .asciidoctorconfig file. Front matter is detected at the very top of the file, before the document header and before either of those sources is applied, so a :skip-front-matter: declared there is read too late to have any effect.

Source code highlighting

Source blocks are highlighted out of the box using the bundled Highlight.js highlighter — you don’t need to set :source-highlighter: for the preview.

[source,ruby]
----
puts 'Hello, World!'
----

This also applies to HTML-based exports (HTML and the wkhtmltopdf engine of Export as PDF). DocBook export is not affected: DocBook is a semantic format, so source highlighting is left to the DocBook publishing toolchain. Likewise, PDFs generated with the asciidoctor-pdf engine rely on the Ruby toolchain’s own highlighters (for example Rouge).

The built-in highlighter is a soft default: a document that declares its own :source-highlighter: keeps it. To change or disable the highlighter globally, use the asciidoc.preview.asciidoctorAttributes setting:

pick another highlighter, for example:

"asciidoc.preview.asciidoctorAttributes": {
  "source-highlighter": "highlight.js"
}

disable highlighting by setting an empty value:

"asciidoc.preview.asciidoctorAttributes": {
  "source-highlighter": ""
}

Supported languages

The preview detects the languages used in your source blocks and loads the matching Highlight.js grammar automatically, so any of the languages supported by Highlight.js works without configuration — you don’t need :highlightjs-languages:.

Use the canonical Highlight.js language name. For example, Highlight.js has no zsh grammar; use bash instead.

For HTML-based exports the detection does not apply: list the extra languages you need with the highlightjs-languages attribute (a comma-separated list), either in the document header or through the asciidoc.preview.asciidoctorAttributes setting.

:source-highlighter: highlight.js
:highlightjs-languages: dockerfile, powershell

Styling

By default, the preview uses the VS Code editor theme (workbench.colorTheme).

To use the default Asciidoctor style instead, set asciidoc.preview.useEditorStyle to false.
To replace the stylesheet with your own, set asciidoc.preview.style.
To extend the style without losing the defaults, add your stylesheets to asciidoc.preview.additionalStyles. They are layered on top of the base style (default or custom), in order, so they take precedence — ideal for tweaking a few rules while keeping the built-in look.
To define custom templates, set asciidoc.preview.templates.

See the preview settings for the full list of options.

The `stylesheet` document attribute

When asciidoc.preview.style is not set, the preview also honors the standard stylesheet (and stylesdir) document attributes, so the preview matches the stylesheet used by the generated HTML:

= My document
:stylesdir: css
:stylesheet: my-theme.css

Like asciidoc.preview.style, a stylesheet attribute replaces the default preview stylesheet; asciidoc.preview.additionalStyles are still layered on top of it.

Resolution and precedence:

The asciidoc.preview.style setting always wins. When it is set, the stylesheet/stylesdir attributes are ignored by the preview.
An absolute path or a URL (http:, https:, file:) stylesheet is used as-is (and stylesdir is ignored).
A relative stylesheet is looked up under stylesdir, relative to the document’s base directory — the same base directory Asciidoctor uses. By default, that is the folder containing the AsciiDoc file; when asciidoc.useWorkspaceRootAsBaseDirectory is enabled it is the workspace root, so a relative stylesheet resolves the same way it does in the exported HTML.

For security reasons, the preview webview can only load local files from a fixed set of locations: the workspace folders, or — when the document does not belong to a workspace — the folder containing the AsciiDoc file. A stylesheet that resolves outside those locations — typically an absolute path pointing elsewhere on disk, or a relative path that climbs out of the workspace with ../ — is blocked and silently falls back to no custom stylesheet.

Keep the stylesheet inside the workspace (or next to the document), or use the asciidoc.preview.style setting instead: unlike the attribute, that setting also whitelists its own directory, so it can load a stylesheet kept outside the workspace. A URL (https:) stylesheet is not affected by this restriction. This limitation is specific to the preview; the exported HTML is not sandboxed and loads the stylesheet from anywhere.

This differs from the asciidoc.preview.style and asciidoc.preview.additionalStyles settings, whose relative paths are resolved relative to the folder open in the Explorer (or, with no open folder, relative to the AsciiDoc file) regardless of asciidoc.useWorkspaceRootAsBaseDirectory.

The two follow different conventions on purpose, because they are different kinds of value: configuration paths follow the editor’s conventions, content paths follow Asciidoctor’s.

A setting is editor configuration, typically defined once for a project (in .vscode/settings.json) and shared by every document. It cannot meaningfully be resolved against a document’s base directory: a single asciidoc.preview.style applies to all open documents, which each have their own base directory, so a relative path there would point at a different file per document — almost never the intent. Resolving it relative to the workspace matches how other VS Code path settings behave.
The stylesheet attribute is document content, and its meaning is defined by Asciidoctor. Resolving it against the document’s base directory is what keeps the preview identical to the exported HTML.

The preview is HTML styled with CSS, so it uses the settings above — not an asciidoctor-pdf theme. A PDF theme (theme.yml, set through :pdf-theme: / :pdf-themesdir:) only affects the asciidoctor-pdf engine of Export as PDF and never changes the preview’s appearance.

Sync scrolling

The editor and the preview stay in sync as you scroll, and the current selection is highlighted in the preview. This behaviour is configurable — see the preview settings.

Two VS Code editor settings make the synchronization smoother:

editor.smoothScrolling: Turn it on. The editor can only be scrolled to whole lines, so when it follows the preview it advances one line at a time. Smooth scrolling animates the transition between those positions, so the follow looks gradual instead of stepwise.
editor.stickyScroll.enabled: Turn it off while you rely on scroll sync. Sticky scroll overlays the ancestor headings on top of the editor viewport, hiding the first lines, so the line at the top of the editor looks a few lines off from the top of the preview even though the mapping is correct.

{
  "editor.smoothScrolling": true,
  "editor.stickyScroll.enabled": false
}

Troubleshooting the preview

The preview updates incrementally: when you edit, only the blocks that changed are re-rendered (re-running MathJax, Mermaid and syntax highlighting just for them), and the scroll position is kept stable.

If the preview seems slow to update, gets out of sync, or a block is not re-rendered, enable verbose tracing and inspect the preview console:

Run Developer: Set Log Level…, choose Asciidoctor, then pick Trace (see Get help → Logs).
Reload the window (command Developer: Reload Window).
Open the preview console with the command Developer: Open Webview Developer Tools and look at the [asciidoc.preview] messages while you edit.

The messages report each update, how many blocks were re-rendered (and whether they carry a content hash), and the time spent typesetting math — useful information to include in a bug report.