Asciidoctor configuration file

To provide a common set of attributes when rendering the preview, the extension reads an .asciidoctorconfig or .asciidoctorconfig.adoc configuration file.

This is useful to optimize the preview when a project contains a document split across multiple include files: define the attributes those includes rely on once, and the preview resolves them consistently.

This feature is inspired by the implementation in the IntelliJ AsciiDoc plugin, also reused in the Eclipse AsciiDoc plugin. Keeping the same convention means a project’s configuration is portable across editors.

Create a configuration file

Create a file named .asciidoctorconfig (or .asciidoctorconfig.adoc) and treat it as the header of every document it applies to. It typically contains document attribute declarations, but any header content works — include:: directives and preprocessor conditionals included.

:source-highlighter: highlight.js
:icons: font
:experimental:
:product-name: ACME Rocket

A document rendered next to this file can now use {product-name} and gets the highlighter, admonition icons and UI macros without repeating those attributes in each file.

Where the extension looks for it

The extension applies every configuration file found on the way from the workspace folder down to the document, from the most general to the most specific:

  1. the root of the workspace folder that contains the document;

  2. every intermediate directory between that root and the document;

  3. the directory that contains the document itself.

When the same attribute is defined in more than one file, the file closest to the document wins. This lets a configuration file at the workspace root set project-wide defaults that a configuration file deeper in the tree can override for a sub-folder.

If a document does not belong to any workspace folder (a loose file opened on its own), the extension walks up the file system from the document’s own directory instead.

Both .asciidoctorconfig and .asciidoctorconfig.adoc are read. When both exist in the same directory, .asciidoctorconfig.adoc is applied after — and therefore takes precedence over — .asciidoctorconfig.

Multi-root workspaces

In a multi-root workspace, the extension also reads an .asciidoctorconfig (or .asciidoctorconfig.adoc) sitting at the root of the other workspace folders.

These act as the most general configuration — they are applied first, before the document’s own folder chain, so anything defined closer to the document still wins. This is handy to keep shared configuration and assets (a docinfo folder, a custom stylesheet, …) in a dedicated folder added to the workspace, while each documentation folder keeps its own, more specific configuration:

my.code-workspace
├── shared/                 (1)
│   ├── .asciidoctorconfig
│   └── docinfo/
└── docs/                    (2)
    ├── .asciidoctorconfig
    └── guide.adoc
1 A workspace folder dedicated to shared configuration; its .asciidoctorconfig applies to documents in every folder.
2 The documentation folder; its .asciidoctorconfig refines or overrides the shared values for guide.adoc.

Reference files relative to the config: {asciidoctorconfigdir}

Before applying a configuration file, the extension sets the asciidoctorconfigdir attribute to the absolute path of the directory that contains it. Use it to point at resources from the configuration file with paths that stay correct wherever the edited document lives:

:docinfodir: {asciidoctorconfigdir}/docinfo
:stylesdir: {asciidoctorconfigdir}/styles
:imagesdir: {asciidoctorconfigdir}/images

This is the portable, IDE-agnostic way to anchor paths — prefer it over editor-specific variables such as ${workspaceFolder}, so the same configuration file keeps working in other editors and with the Asciidoctor CLI.

Migrate from useWorkspaceRootAsBaseDirectory

The asciidoc.useWorkspaceRootAsBaseDirectory setting is deprecated and will be removed in a future release. It works by moving Asciidoctor’s base directory to the workspace root so that documents scattered across folders can reference a shared folder with the same path. Overriding the base directory is a known footgun: it detaches {docdir} from the current file and forces every relative include::/image:: path — even one targeting a sibling of the document — to be written relative to the workspace root.

You can achieve the same shared-folder result without touching the base directory: keep the default base directory (the document’s own folder) and anchor the shared paths on {asciidoctorconfigdir} instead. Because {asciidoctorconfigdir} is an absolute path, a document resolves those paths the same way wherever it lives — and, unlike the setting, the configuration is portable to the Asciidoctor CLI and other editors.

Single-folder workspace

Say several documents in different folders all pull includes from docs/_includes/ and images from resources/, and you relied on useWorkspaceRootAsBaseDirectory so each document could write those paths from the workspace root.

Add an .asciidoctorconfig at the workspace root:

my-project/
├── .asciidoctorconfig        (1)
├── docs/
│   └── _includes/
├── resources/
└── chapters/
    └── intro.adoc            (2)
1 Anchors the shared folders on the workspace root.
2 Keeps its own default base directory, so {docdir} still points at chapters/. 
:imagesdir: {asciidoctorconfigdir}/resources

Then reference the shared folders through the anchor — write include::{asciidoctorconfigdir}/docs/_includes/legal.adoc[] instead of include::docs/_includes/legal.adoc[], and images already resolve under the imagesdir set above. A path that targets a file next to the current document keeps working as a plain relative path, because the base directory was never moved.

Multi-root workspace

For the multi-root case — documents under a project1 folder that reference a resources/ folder living in a different work folder — put the .asciidoctorconfig at the root of the folder that holds the shared resources:

my.code-workspace
├── work/                     (1)
│   ├── .asciidoctorconfig
│   └── resources/
└── project1/                 (2)
    └── guide.adoc
1 The folder holding the shared resources; its .asciidoctorconfig is read for documents in every workspace folder (see Multi-root workspaces).
2 guide.adoc references the shared folder through {asciidoctorconfigdir}, e.g. image::{asciidoctorconfigdir}/resources/logo.png[].

This covers the shared-folder use case of a multi-root workspace without any base-directory setting: no useWorkspaceRootAsBaseDirectory, and no need to point the base directory at a named folder such as ${workspaceFolder:work}.

Switch between configurations (e.g. web vs. print)

Because a configuration file is processed as an AsciiDoc header, you can keep several profiles in one file and toggle them with preprocessor conditionals. Name the file .asciidoctorconfig.adoc — the ifdef/ifndef/ifeval directives only run when the file has the .adoc extension.

ifndef::print[]
:stylesheet: web.css
:docinfo: shared,private
endif::[]
ifdef::print[]
:stylesheet: book.css
:media: prepress
endif::[]

Set the switching attribute (here print) where it suits your workflow — for example through asciidoc.preview.asciidoctorAttributes in the workspace settings, or on the export command line.

Limitations

  • Preprocessor conditionals (ifdef::, ifndef::, ifeval::) are only evaluated in a file named .asciidoctorconfig.adoc, not in .asciidoctorconfig.

  • The configuration is read as a document header: put attribute declarations and header-level directives in it, not body content.