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.

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 {
      /* ... */
    }

Add additional styles or HTML headers

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

  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>