Although I liked the appearance of the Airspace theme, it was clear that I would need to make some changes to, minimally, specify the text and background colours, and to provide styling for AsciiDoc-related markup.

Some colours can be altered in the themes\airspace-hugo\config.toml file, but the options are limited:

config.toml
# customize your color and font from here.
[params.variables]
color_primary = "#655e7a"
body_color = "#fff"
text_color = "#666666"
text_dark = "#333333"
text_light = "#7b7b7b"
border_color = "#ACB9C4"
black = "#000000"
white = "#ffffff"
light = "#f5f5f5"

Out the box Hugo processes .adoc files using AsciiDoctor provided that AsciiDoctor is installed on your system. However, most themes don’t provide styling for AsciiDoc, so tables, admonitions (notes, tips, cautions and so forth) and code block are unformatted.

At first, I simply overrode some of the Airspace SCSS by adding rules to the \assets\scss\custom.scss file, which is imported by default in the \themes\airspace-hugo\assets\scss\style.scss file.

I soon realized, though, that I would need to make more substantial changes.

The Airspace SCSS is not particularly DRY: font and background colours, font sizes, line heights and so on are all individually set, with considerable inconsistency.

For this reason, I did the following:

  1. Added a vars.scss file to \themes\airspace-hugo\assets\scss.

  2. Renamed variables to be more consistent, for example:

    Original Revised

    $color-primary

    $color-brand-1

    $color-secondary

    $color-brand-2

    $text-color

    $color-text

  3. Replaced non-DRY rules, such as line-height: 16px;, with DRY ones, such as line-height: $line-height-base;.

  4. Replaced absolute measurements (mostly px) with relative ones (rem or em, depending on the context), except for things like border widths.

  5. Added a _asciidoc.scss file to \themes\airspace-hugo\assets\scss\templates and added the line @import '_asciidoc.scss' to the end of style.scss file.

    The _asciidoc.scss file contains all the rules needed to correctly format the HTML generated by AsciiDoctor. It’s not yet comprehensive, but it’s easy to add new rules as required.