Settings

This extension contributes the settings below. You can edit them from the VS Code Settings UI or directly in settings.json.

Preview

Name Description Default

asciidoc.preview.asciidoctorAttributes

Asciidoctor attributes used in the preview (object of {string: string}).

{}

asciidoc.preview.refreshInterval

Interval in milliseconds between two consecutive preview updates. The value 0 updates the preview only on save.

2000

asciidoc.preview.defaultStyle

Built-in stylesheet used when asciidoc.preview.style is empty and the document does not set stylesheet/stylesdir. Possible values: ` (Automatic — follows `asciidoc.preview.useEditorStyle, and switches to antora when Antora support is active), vscode, asciidoctor, antora, github (matches light or dark to the active VS Code color theme).

`` (Automatic)

asciidoc.preview.style

A URL or local path to a CSS stylesheet that replaces the default preview stylesheet. When left empty, the preview falls back to the document’s stylesheet/stylesdir attributes (see the stylesheet attribute).

asciidoc.preview.additionalStyles

A list of URLs or local paths to CSS stylesheets layered on top of the preview style (default or custom), in order, so they keep the defaults and take precedence.

[]

asciidoc.preview.useEditorStyle

Deprecated. Use asciidoc.preview.defaultStyle instead.

asciidoc.preview.fontFamily

Font family used in the preview.

-apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', 'HelveticaNeue-Light', 'Ubuntu', 'Droid Sans', sans-serif

asciidoc.preview.fontSize

Font size, in pixels, used in the preview.

14

asciidoc.preview.lineHeight

Line height used in the preview.

1.6

asciidoc.preview.scrollPreviewWithEditor

When the preview is scrolled, update the editor view.

true

asciidoc.preview.scrollEditorWithPreview

When the editor is scrolled, update the preview view.

true

asciidoc.preview.markEditorSelection

Mark the current editor selection in the preview.

true

asciidoc.preview.doubleClickToSwitchToEditor

Double-click in the preview to switch to the editor.

true

asciidoc.preview.preservePreviewWhenHidden

Keep the preview in memory while it is hidden so it reloads faster, at the cost of increased memory use.

false

asciidoc.preview.openLinksToAsciidocFiles

How links to other AsciiDoc files open in the preview. Possible values: inPreview, inEditor.

inPreview

PDF

Name Description Default

asciidoc.pdf.engine

PDF engine used to export as PDF. Possible values: asciidoctor-pdf, wkhtmltopdf.

asciidoctor-pdf

asciidoc.pdf.asciidoctorPdfCommandPath

External asciidoctor-pdf command to run. Accepts a full path to the binary, for instance /path/to/asciidoctor-pdf.

bundle exec asciidoctor-pdf

asciidoc.pdf.asciidoctorPdfCommandArgs

List of arguments, for instance -a, pdf-themesdir=resources/themes, -a, pdf-theme=basic. The key and value must be added as separate items. By default, the extension passes --quiet and --base-dir with the full directory path to the document.

[]

asciidoc.pdf.wkhtmltopdfCommandPath

External wkhtmltopdf command to run. Accepts a full path to the binary. When empty, uses wkhtmltopdf on Linux/macOS or wkhtmltopdf.exe on Windows.

""

asciidoc.pdf.wkhtmltopdfCommandArgs

List of arguments, for instance --orientation, Landscape. The key and value must be added as separate items. By default, the extension passes --enable-local-file-access, --encoding, utf-8, --javascript-delay, 1000, --footer-center (if enabled), and cover (if a cover page is present).

[]

asciidoc.pdf.outputDirectory

Directory where the exported PDF is written. When empty, the PDF is saved next to the document. A relative path is resolved against the workspace folder (or the document directory when there is no workspace); ${workspaceFolder} is supported. The directory is created if it does not exist. See Output location.

""

asciidoc.pdf.askOutputLocation

Ask for the output location every time a PDF is exported. When disabled, the PDF is written directly to asciidoc.pdf.outputDirectory (or next to the document) without prompting, overwriting any existing file.

true

Extensions

Name Description Default

asciidoc.extensions.enableKroki

Enable the Kroki extension to generate diagrams.

false

asciidoc.extensions.kroki.serverUrl

URL of the Kroki server used to render diagrams (for example localhost:8000 for a self-hosted instance). Leave empty to use the public kroki.io server. A kroki-server-url attribute set in the document header or in an .asciidoctorconfig file takes precedence over this setting.

(empty)

asciidoc.extensions.registerWorkspaceExtensions

Enable registration of Asciidoctor.js extensions from the workspace directory .asciidoctor/lib.

false

General

Name Description Default

asciidoc.useWorkspaceRootAsBaseDirectory

(deprecated) Resolve relative includes and images against the workspace root instead of the current file’s directory. See Base directory resolution.

false

Base directory resolution

By default, Asciidoctor resolves the relative paths in a document (include::, image::, link:, …) against the directory of the current file. Enabling asciidoc.useWorkspaceRootAsBaseDirectory sets Asciidoctor’s base directory to the root of the workspace folder that contains the document instead. This is useful when several documents, spread across different folders, all reference a shared folder (for example docs/_includes/) with the same path.

The setting is applied consistently to the preview, the HTML/DocBook export and the PDF export, so a document resolves the same way everywhere.

When the setting is enabled, Asciidoctor ties the intrinsic {docdir} attribute to the base directory, so {docdir} resolves to the workspace root, not the folder containing the current file. As a result:

  • Every relative include::/image:: path in the top-level document must be written relative to the workspace root — including one that targets a file sitting next to the current document.

  • {docdir} cannot be used to reach a sibling of the current file.

  • Includes located inside an already-included file are still resolved relative to that included file.

Leaving the setting disabled (the default) is recommended: an explicit base directory is a known footgun that can break relative includes.

This setting is deprecated and will be removed in a future release. Use an .asciidoctorconfig file to share a folder across documents instead — see Migrate from useWorkspaceRootAsBaseDirectory for the equivalent setup.

Editor defaults

Besides the asciidoc. settings above, the extension also sets a few *VS Code editor defaults for AsciiDoc files through the configurationDefaults contribution point:

"[asciidoc]": {
  "editor.wordWrap": "on",
  "editor.wordBasedSuggestions": "off",
  "editor.quickSuggestions": {
    "comments": "off",
    "strings": "off",
    "other": "off"
  }
}

Word wrap is on because AsciiDoc is a prose format. The two suggestion settings are off on purpose: word-based suggestions (the editor proposing other words already present in the document) and the automatic suggestion pop-up add noise while you type structured constructs such as attribute references {name}, attribute entries :name: or cross references, where the extension already provides its own, context-aware completion.

Overriding these defaults

These are only defaults: you can override any of them in your own settings.json. For example, to get the editor to suggest words from the document while writing prose:

"[asciidoc]": {
  "editor.wordBasedSuggestions": "matchingDocuments",
  "editor.quickSuggestions": {
    "other": "on"
  }
}

Scope your override under [asciidoc], as shown above — not as a plain top-level "editor.wordBasedSuggestions". VS Code applies language-specific settings over non-language-specific ones regardless of scope, so a top-level value never wins against the extension’s [asciidoc] default.

In practice this means changing a setting from the Settings UI search box (for example toggling Editor: Word Wrap) has no effect on AsciiDoc files: VS Code writes a non-language-specific value there, which the [asciidoc] default overrides. To override a default, use an AsciiDoc-specific setting instead, any of:

  • run Preferences: Configure Language Specific Settings… from the Command Palette and pick AsciiDoc;

  • filter the Settings UI with @lang:asciidoc, then change the setting;

  • or edit settings.json directly with an [asciidoc] block, as shown above.

When you work over Remote-SSH, in a dev container or over WSL, the extension runs on the remote machine and so do its defaults. Put the [asciidoc] override in your Remote (or Workspace) settings.json, not the local one, otherwise it has no effect on the remotely opened files.

Debug

Name Description Default

asciidoc.debug.enableErrorDiagnostics

Provide error diagnostics.

true

The extension writes its logs to a dedicated Asciidoctor output channel. See Get help → Logs to learn how to view them and change their verbosity.

The asciidoc.debug.trace setting is deprecated and no longer has any effect. Logging verbosity is now controlled by VS Code through the Developer: Set Log Level…​ command.