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 you 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 subfolders. 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. Therefore, the user will not be able to work off-line anymore. Consider using a conditional like ifdef to provide an attribute for the user to switch off the custom stylesheets when they are offline.

Replace default stylesheet

This replaces the standard stylesheet with a custom stylesheet. You can use local content, or link to a remote stylesheet.

Using local project’s content

The stylesheet will be embedded in the preview, therefore relative links to the local file system will not work.
  1. 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.
  2. Place your stylesheet in the .asciidoctor folder:

    .asciidoctor/preview-stylesheet.css
    body {
      /* ... */
    }

Using a remote stylesheet

This is available from 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:

  1. Create a file .asciidoctorconfig with the following contents:

    .asciidoctorconfig
    :linkcss:
    :stylesdir: https://example.com/css
    :stylesheet: preview-stylesheet.css
  2. 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 {
      /* ... */
    }

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

Dark theme based on the asciidoctor-skins project
:linkcss:
:stylesdir: https://darshandsoni.com/asciidoctor-skins/css
:stylesheet: dark.css

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:

  1. 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
  2. Place your docinfo.html in the .asciidoctor folder

    .asciidoctor/docinfo.html
    <style>
    body {
      /* ... */
    }
    </style>