Custom stylesheets for the preview

The user can provide custom stylesheets for the preview to make the preview look similar to the live site they publish the content to.

Configuring stylesheets

This chapter walks the user through the steps to prepare an .asciidoctorconfig file to either replace the stylesheet or to add additional styles to the HTML header.

The .asciidoctorconfig file will configure the preview of all AsciiDoc files in the folder where it is located and this folder’s sub-folders. See Asciidoctor Config File for more details.

If the configuration references remote content like fonts or stylesheets, these will require an online connection for the preview to load them.
Only JCEF and JavaFX preview support proper stylesheets. Swing preview doesn’t support modern CSS, and will therefore not support custom CSS.
New with version 0.35.16: If no online connection exists, or the local stylesheet is missing, the preview defaults to the standard stylesheet.

Replace default stylesheet

This replaces the standard stylesheet with a custom stylesheet. Use local content or link to a remote stylesheet.

Using local project’s content

Create a file .asciidoctorconfig with the following contents:
.asciidoctorconfig
```
:stylesdir: {asciidoctorconfigdir}/.asciidoctor (1)
:stylesheet: preview-stylesheet.css (2)
```
1 Point to a directory with the stylesheet. As this uses {asciidoctorconfigdir}, the folder is relative to the .asciidoctorconfig file.

2 Filename of the stylesheet to be used.
Place the stylesheet in the .asciidoctor folder:
.asciidoctor/preview-stylesheet.css
```
body {
  /* ... */
}
```

Using a remote stylesheet

This has been available since the plugin version 0.31.31+.

Once the document or the configuration set the linkcss attribute, the preview will link to an external stylesheet and will no longer embed the stylesheet.

Apply the following steps:

Create a file .asciidoctorconfig with the following contents:

.asciidoctorconfig

:linkcss:
:stylesdir: https://example.com/css
:stylesheet: preview-stylesheet.css

Host an external stylesheet
In the example above, the preview will fetch it from https://example.com/css/preview-stylesheet.css
preview-stylesheet.css
```
body {
  /* ... */
}
```

Due to the current nature of the plugin and browser’s security controls, a stylesheet can’t load fonts with a relative path starting with two dots (..).

As a workaround, use an absolute path with protocol and hostname instead.

A more complex example that wraps multiple stylesheets of the original site, overwrites fonts with an absolute URL and then adds custom changes for the preview can look like the following:

Example CSS customizing the existing stylesheets for the IDE’s preview

@import "site1.css";
@import "site2.css";

/* workaround for browsers that don't allow relative URLs when the page is opened as a file:// */
@font-face {
    font-family: ...
    src: url('https://example.com/');
}

/* skip the space at the top in the preview where the menu bar is on the production site */
body {
    padding-top: 0
}

The asciidoctor-skins project hosts multiple stylesheets users can link to. The following example uses a dark skin.

Fedora theme based on the asciidoctor-skins project

:linkcss:
:stylesdir: https://darshandsoni.com/asciidoctor-skins/css
:stylesheet: fedora.css

If the remote stylesheet is not available due to an unreachable server or a missing stylesheet, the preview will default to the standard stylesheet. Starting with release 0.37.52 of the plugin, the preview shows an error message to notify the user that this happened.

To debug problems with remote stylesheets, use the DevTools available for the JCEF preview. Looking at the console or network tab reveals the full error message why a remote stylesheet wasn’t loaded.

Add additional styles or HTML headers

This adds additional styles and HTML headers in addition to the default stylesheet. The chapter “Docinfo Files” in the Asciidoctor User Manual provides more information about this capability.

The contents will be embedded in the preview, therefore, relative links to the local file system will not work.
Attribute substitution is supported in plugin version 0.31.35+. To prevent an infinite recursion, substitution is limited to 100 attributes and 20 substitutions per attribute.

Follow these steps to enable Docinfo Files:

Create a file .asciidoctorconfig with the following contents:

.asciidoctorconfig

:docinfodir: {asciidoctorconfigdir}/.asciidoctor (1)
:docinfo: shared (2)

1	Point to a directory with docinfo files. As this uses {asciidoctorconfigdir}, the folder is relative to the .asciidoctorconfig file.
2	Tell the renderer to include the shared docinfo file docinfo.html.

Place the docinfo.html in the .asciidoctor folder
.asciidoctor/docinfo.html
```
<style>
body {
  /* ... */
}
</style>
```

1	Point to a directory with the stylesheet. As this uses {asciidoctorconfigdir}, the folder is relative to the .asciidoctorconfig file.
2	Filename of the stylesheet to be used.