Styling with CSS | Working with adoc Studio

5.1. Prerequisites

adoc Studio
Text editor or IDE with CSS support
Browser with developer tools for testing

This document does not provide a CSS course. If you need CSS knowledge, you will find many resources online. If needed, you can contact external service providers. A partner program with appropriate contacts is currently being established.

5.2. Basics

You can find all styles under adoc Studio Settings… Product Styles. Alternatively, use ⌘+, to open Settings.

Style Categories in adoc Studio

adoc Studio distinguishes between factory styles and custom styles.

Factory Styles: Read-only default designs included with adoc Studio.
Custom Styles: Styles duplicated, created, or imported externally by the user. Custom styles always appear above the factory styles in their own group.

default style.en

Right-click on a style to set it as the default. New projects automatically start with this style.

Viewing Factory Styles

Right-click adoc Studio in your Applications folder to show the package contents of the app.

You can find the factory styles under Contents Resources FactoryStyles. Show the package contents there as well to see the info.json and style.css files for the selected style.

Viewing Custom Styles

There are two ways to view your custom styles:

In Finder: Custom styles are stored under Library Containers app.adoc-studio.main Data Library Application Support Styles.
In adoc Studio: Click the arrow in the toolbar to the right of the symbol. Select your style from the dropdown menu.

If selection is not possible, a lock against changes may be active. You can identify it by the padlock symbol. Click it to remove the lock.

Open a style with a right-click in Finder, or edit it in the text editor of your choice.

You can then show the package contents of the desired .adocstyle file again. (see above for the explanation)

If you manage your files in a Git repository, you can also version your product styles there.
ln -s path/to/your/repository ~/Library/Containers/app.adoc-studio.main/Data/Library/Application Support creates a symbolic link to the required directory.
Make sure to also grant access to this directory in the adoc Studio Settings.

File Structure of a Style Package

The style file is a so-called bundle — a directory presented as a file. This is a common approach on macOS to simplify working with a collection of files.

Click Show Package Contents in Finder to open the file like a folder. The root directory contains info.json, alongside a resources folder that bundles all assets.

The minimal structure is:

StyleName.adocstyle/
   info.json
   resources/
      style.css

File Content

File	Content
`info.json`	Metadata (ID, display name, `basedOn` option, etc.).
`resources/style.css`	All CSS rules. Uses the variable scheme `--ads-*`.

info.json

Metadata (ID, display name, basedOn option, etc.).

resources/style.css

All CSS rules. Uses the variable scheme --ads-*.

The file info.json is a description file in which you define the basic behavior of your style.

Example info.json with explanation

{
"id": "app.adoc-studio.style.example",   // unique internal identifier
"name": "Example",                       // display name in adoc Studio
"basedOn": "app.adoc-studio.style.base", // optional: ID of the base style
"isHidden": false,                       // true hides the style in the menu
}

Note on the ID: adoc Studio uses the ID to reference the style. If you duplicated a style file from another style, you will find a UUID here that you do not need to edit. You can also use a custom identifier like the example: "id": "app.adoc-studio.style.example"

In addition, a style can contain any content such as fonts or images used in the style.

A more complex example:

StyleName.adocstyle/
   info.json
   fonts/
      font1.ttf
      font2.ttf
   images/
      logo.jpg
      icon.png
   resources/
      style.css

In the CSS file, reference individual components using the bundle as the root directory. The path to a font file is therefore fonts/font1.ttf.

5.3. Creating Custom Styles (3 Approaches)

Duplicate and Adapt a Base Style (recommended for CSS beginners)

Open Settings or click menu:…[Edit Style] in the preview settings.
Select a base style and click Duplicate.
Open the new style via Show in Finder → Show Package Contents.
Edit style.css in your editor.

:root {
    --ads-headline-color: #cc0000;
    --ads-a-color: #0066cc;
}

External CSS File via Document Attribute

Create custom-style.css in the project folder.
Remove any automatically set title lines if needed.
Include the file in the document:

:stylesheet: custom-style.css

adoc Studio will then use only this stylesheet.

Style from Scratch (for CSS professionals)

Copy an empty custom style in Finder.
Clear the contents of style.css and info.json.
Define all required variables yourself:

:root {
    --ads-body-font: "Times New Roman", serif;
    --ads-headline-font: "Arial", sans-serif;
    --ads-color: #000;
    --ads-background-color: #fff;
    --ads-a-color: #0066cc;
    --ads-a-hover-color: #0052a3;
    --ads-single-border-color: #ccc;
}

5.4. Variable Concepts

The default stylesheet from Asciidoctor serves as the common foundation. The factory styles are derived from it.

Fonts and colors are stored in a list of variables. This document describes the most common customizations.

adoc Studio uses a structured system of CSS variables with the prefix --ads-.

Global Color and Typography Variables

The most important variable categories:

:root {
    /* Typography */
    --ads-body-font: serif;
    --ads-headline-font: sans-serif;
    --ads-monospaced-font: monospace;
    --ads-toc-font: sans-serif;

    /* Basic Colors */
    --ads-color: #101010;
    --ads-background-color: #ffffff;
    --ads-headline-color: #ba3925;

    /* Links */
    --ads-a-color: #2156a5;
    --ads-a-hover-color: #1d4b8f;

    /* Borders */
    --ads-single-border-color: #dddddf;
    --ads-border-color: rgb(0 0 0 / 0.6);
}

Dark Mode Overrides

Define separate variables for dark mode:

:root {
    --ads-color: #101010;
    --ads-background-color: #ffffff;

    --ads-color-dark: #f1f1f1;
    --ads-background-color-dark: #121212;
}

@media (prefers-color-scheme: dark) {
    body {
        color: var(--ads-color-dark);
        background-color: var(--ads-background-color-dark);
    }

    h1, h2, h3, h4, h5, h6 {
        color: var(--ads-headline-color-dark);
    }
}

A complete list of the variables in adoc Studio can be found here.

5.5. Element Classes

Typography

Body and Body Text

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`.paragraph > p`	Paragraphs	`font-size`, `line-height`, `margin-bottom`
`.paragraph.lead > p`	Preamble	Larger font, `font-weight: 500`
`#preamble > .sectionbody > [class=paragraph]:first-of-type p`	First paragraph	Special formatting for introduction

.paragraph > p

Paragraphs

font-size, line-height, margin-bottom

.paragraph.lead > p

Preamble

Larger font, font-weight: 500

#preamble > .sectionbody > [class=paragraph]:first-of-type p

First paragraph

Special formatting for introduction

/* Body Text Formatting */
.paragraph > p {
    font-size: 1em;
    line-height: 1.6;
    margin-bottom: 1.25em;
    color: var(--ads-color);
}

.paragraph.lead > p {
    font-size: 1.25em;
    font-weight: 500;
    line-height: 1.4;
}

Example in AsciiDoc:

This is an introductory text with a larger font.

This is a regular paragraph with standard formatting.

Headings

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`h1`, `h2`, `h3`, `h4`, `h5`, `h6`	Headings	`font-family`, `font-weight`, `color`, `margin`
`#header > h1:first-child`	Document title	Larger font, centered
`.subtitle`	Subtitle	Smaller font than main title

h1, h2, h3, h4, h5, h6

Headings

font-family, font-weight, color, margin

#header > h1:first-child

Document title

Larger font, centered

.subtitle

Subtitle

Smaller font than main title

h1, h2, h3, h4, h5, h6 {
    font-family: var(--ads-headline-font);
    color: var(--ads-headline-color);
    font-weight: 300;
    line-height: 1.2;
}

#header > h1:first-child {
    font-size: 2.5em;
    text-align: center;
    margin-bottom: 1em;
}

h2 {
    font-size: 1.875em;
    margin-top: 2em;
    margin-bottom: 1em;
}

Inline Formatting

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`strong`, `b`	Bold	`font-weight: bold`
`em`, `i`	Italic	`font-style: italic`
`mark`	Highlight	`background-color`, `padding`
`code`	Inline code	`font-family: monospace`, `background-color`

strong, b

Bold

font-weight: bold

em, i

Italic

font-style: italic

mark

Highlight

background-color, padding

code

Inline code

font-family: monospace, background-color

strong {
    font-weight: bold;
    color: var(--ads-color);
}

mark {
    background-color: var(--ads-mark-background-color);
    padding: 0.1em 0.3em;
    border-radius: 0.2em;
}

code {
    font-family: var(--ads-monospaced-font);
    background-color: var(--ads-pre-background-color);
    padding: 0.1em 0.5em;
    border-radius: 4px;
}

Tables

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`table.tableblock`	Basic table	`border-collapse`, `background-color`
`table thead th`	Table header	`background-color`, `font-weight`
`table.stripes-all > * > tr`	Striped rows	`background-color` alternating
`table.frame-all`	Full frame	`border-width: 1px`
`table.grid-all > * > tr > *`	Full grid	All cell borders

table.tableblock

Basic table

border-collapse, background-color

table thead th

Table header

background-color, font-weight

table.stripes-all > * > tr

Striped rows

background-color alternating

table.frame-all

Full frame

border-width: 1px

table.grid-all > * > tr > *

Full grid

All cell borders

table.tableblock {
    border-collapse: collapse;
    background-color: var(--ads-table-background-color);
    width: 100%;
    margin-bottom: 1.25em;
}

table thead th {
    background-color: var(--ads-table-head-background-color);
    font-weight: bold;
    padding: 0.5em 0.625em;
    border: 1px solid var(--ads-single-border-color);
}

table.stripes-all > * > tr:nth-of-type(odd) {
    background-color: var(--ads-table-stripes-background-color);
}

Example in AsciiDoc:

Name	Description	Status
Feature A	Important functionality	Active
Feature B	Additional option	Beta

Name

Description

Status

Feature A

Important functionality

Active

Feature B

Additional option

Beta

Images and Image Blocks

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`.imageblock`	Image container	`margin`, `text-align`
`.imageblock > .title`	Image caption	`font-size`, `font-style`
`.imageblock.left`	Left-aligned image	`float: left`, `margin-right`
`.imageblock.right`	Right-aligned image	`float: right`, `margin-left`
`img`	Image element	`max-width: 100%`, `height: auto`

.imageblock

Image container

margin, text-align

.imageblock > .title

Image caption

font-size, font-style

.imageblock.left

Left-aligned image

float: left, margin-right

.imageblock.right

Right-aligned image

float: right, margin-left

img

Image element

max-width: 100%, height: auto

.imageblock {
    margin: 1.25em 0;
    text-align: center;
}

.imageblock > .title {
    font-style: italic;
    font-size: 0.9em;
    margin-top: 0.5em;
    color: var(--ads-details-color);
}

.imageblock.left {
    float: left;
    margin: 0.25em 1.25em 1.25em 0;
    text-align: left;
}

img {
    max-width: 100%;
    height: auto;
    border-radius: 4px;
}

Example in AsciiDoc:

.Example image with caption
image::example.png[alt="Example", width=400]

[.left]
.Left-aligned image
image::logo.png[alt="Logo", width=200]

Lists and Checklists

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`.ulist ul`	Unordered list	`list-style-type`, `margin`
`.olist ol`	Ordered list	`list-style-type: decimal`
`.checklist ul`	Checklist	`list-style-type: none`
`.dlist`	Definition list	Special formatting for term/definition
`.hdlist`	Horizontal definition list	Table-like layout

.ulist ul

Unordered list

list-style-type, margin

.olist ol

Ordered list

list-style-type: decimal

.checklist ul

Checklist

list-style-type: none

.dlist

Definition list

Special formatting for term/definition

.hdlist

Horizontal definition list

Table-like layout

.ulist ul {
    list-style-type: disc;
    margin-left: 1.5em;
    line-height: 1.6;
}

.ulist ul li {
    margin-bottom: 0.5em;
}

.checklist ul {
    list-style-type: none;
    margin-left: 0;
}

.checklist ul li::before {
    content: "☐ ";
    margin-right: 0.5em;
}

.checklist ul li.checked::before {
    content: "☑ ";
}

dl dt {
    font-weight: bold;
    margin-top: 1em;
    color: var(--ads-headline-color);
}

dl dd {
    margin-left: 1.5em;
    margin-bottom: 0.5em;
}

Example in AsciiDoc:

First item
Second item
- Sub-item
- Another sub-item

Task 1
Task 2 (done)
Task 3

Term

Definition of the term

Another term

Further definition

Code and Syntax Highlighting

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`.listingblock`	Code block container	`background-color`, `border-radius`
`.listingblock > .content > pre`	Code content	`font-family: monospace`, `overflow-x`
`.code-keyword`	Keywords	`color`, `font-weight: bold`
`.code-string`	Strings	`color` (usually green or blue)
`.code-comment`	Comments	`color` (usually gray), `font-style: italic`

.listingblock

Code block container

background-color, border-radius

.listingblock > .content > pre

Code content

font-family: monospace, overflow-x

.code-keyword

Keywords

color, font-weight: bold

.code-string

Strings

color (usually green or blue)

.code-comment

Comments

color (usually gray), font-style: italic

.listingblock {
    margin-bottom: 1.25em;
}

.listingblock > .content > pre {
    background-color: var(--ads-listingblock-background-color);
    padding: 1em;
    border-radius: 4px;
    overflow-x: auto;
    font-family: var(--ads-monospaced-font);
    font-size: 0.9em;
    line-height: 1.4;
}

/* Syntax Highlighting */
.code-keyword {
    color: var(--ads-literal-color);
    font-weight: bold;
}

.code-string {
    color: var(--ads-attribute-color);
}

.code-comment {
    color: var(--ads-comment-color);
    font-style: italic;
}

.code-function {
    color: var(--ads-tag-color);
}

Example in AsciiDoc:

function exampleFunction() {
    // This is a comment
    const variable = "string value";
    return variable;
}

.example-class {
    color: red;
    font-size: 1.2em;
    }

Admonitions

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`.admonitionblock`	Admonition container	`margin`, `border`, `background-color`
`.admonitionblock.note`	Note (blue)	Blue colors
`.admonitionblock.tip`	Tip (green)	Green colors
`.admonitionblock.warning`	Warning (orange)	Orange colors
`.admonitionblock.caution`	Caution (yellow)	Yellow colors
`.admonitionblock.important`	Important (red)	Red colors
`.admonitionblock td.icon`	Icon area	Icon formatting
`.admonitionblock td.content`	Text content	Text formatting

.admonitionblock

Admonition container

margin, border, background-color

.admonitionblock.note

Note (blue)

Blue colors

.admonitionblock.tip

Tip (green)

Green colors

.admonitionblock.warning

Warning (orange)

Orange colors

.admonitionblock.caution

Caution (yellow)

Yellow colors

.admonitionblock.important

Important (red)

Red colors

.admonitionblock td.icon

Icon area

Icon formatting

.admonitionblock td.content

Text content

Text formatting

.admonitionblock {
    margin: 1.25em 0;
    border-left: 5px solid;
    background-color: var(--ads-admonitionblock-background-color);
}

.admonitionblock.note {
    border-color: var(--ads-note-border-color);
    background-color: var(--ads-note-background-color);
}

.admonitionblock.tip {
    border-color: var(--ads-tip-border-color);
    background-color: var(--ads-tip-background-color);
}

.admonitionblock.warning {
    border-color: var(--ads-warning-border-color);
    background-color: var(--ads-warning-background-color);
}

.admonitionblock td.icon {
    width: 80px;
    text-align: center;
    padding: 1em;
}

.admonitionblock td.content {
    padding: 1em;
    word-wrap: anywhere;
}

/* Icons with Font Awesome */
.admonitionblock td.icon .icon-note::before {
    content: "\f05a";
    color: var(--ads-note-color);
    font-size: 2em;
}

.admonitionblock td.icon .icon-tip::before {
    content: "\f0eb";
    color: var(--ads-tip-color);
    font-size: 2em;
}

Example in AsciiDoc:

This is an important note for the reader.

Here is a useful tip.

Caution is required here!

Proceed with extra care.

This is very important to note.

Navigation and Table of Contents

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`.tocbase`	TOC container	`background-color`, `border`, `padding`
`#toctitle`	TOC heading	`font-size`, `font-weight`, `color`
`.tocbase ul`	TOC lists	`list-style: none`, `margin`
`.tocbase li`	TOC entries	`line-height`, `margin`
`.tocbase a`	TOC links	`text-decoration: none`, `color`

.tocbase

TOC container

background-color, border, padding

#toctitle

TOC heading

font-size, font-weight, color

.tocbase ul

TOC lists

list-style: none, margin

.tocbase li

TOC entries

line-height, margin

.tocbase a

TOC links

text-decoration: none, color

.tocbase {
    background-color: var(--ads-toc-background-color);
    border: 1px solid var(--ads-single-border-color);
    padding: 1.25em;
    margin-bottom: 1.25em;
    border-radius: 4px;
}

#toctitle {
    font-size: 1.375em;
    font-weight: 500;
    color: var(--ads-headline-color);
    margin-bottom: 0.5em;
}

.tocbase ul {
    list-style: none;
    margin: 0;
    padding-left: 0;
}

.tocbase li {
    line-height: 1.4;
    margin-top: 0.5em;
}

.tocbase a {
    text-decoration: none;
    color: var(--ads-a-color);
}

.tocbase a:hover {
    color: var(--ads-a-hover-color);
    text-decoration: underline;
}

/* Indentation for sub-levels */
.tocbase ul ul {
    padding-left: 1em;
    margin-top: 0.25em;
}

Using Custom Classes

You can define custom classes and activate them directly in the text. Place the class name in square brackets ([.custom-class]) before the corresponding element.

Examples in AsciiDoc:

This text is red.

This text is horizontally centered.

Colors

/* Text colors */
.red { color: var(--ads-red-color); }
.blue { color: var(--ads-blue-color); }
.green { color: var(--ads-green-color); }

/* Background colors */
.red-background { background-color: var(--ads-red-background-color); }
.blue-background { background-color: var(--ads-blue-background-color); }
.green-background { background-color: var(--ads-green-background-color); }

@media (prefers-color-scheme: dark) {
    .red { color: var(--ads-red-color-dark); }
    .blue { color: var(--ads-blue-color-dark); }
    .green { color: var(--ads-green-color-dark); }
}

Float and Alignment

.left { float: left !important; }
.right { float: right !important; }
.text-left { text-align: left !important; }
.text-right { text-align: right !important; }
.text-center { text-align: center !important; }
.text-justify { text-align: justify !important; }
.hide { display: none; }
.clearfix::after {
    content: "";
    display: table;
    clear: both;
}

5.6. PDF Output with Vivliostyle

Purpose and Function

Vivliostyle is a JavaScript engine for CSS Paged Media. adoc Studio uses it to paginate the HTML preview into a print-ready PDF. All PDF-specific rules are therefore encapsulated in their own block:

@media vivliostyle { … }

Inside this block, the same CSS selectors apply as in the browser, extended by paged-media properties such as @page, string-set, or counter-increment.

Global Control

Element Purpose Typical Value

Element	Purpose	Typical Value
`--ads-page-size`	Passes the configured page size to the print dialog.	`A4 portrait`
`--ads-page-margin`	Default page margin.	`2.5cm`
`:root[data-pagenums]`	Enables counted page types (see below).	`cover`, `title`, `toc`, `body`

--ads-page-size

Passes the configured page size to the print dialog.

A4 portrait

--ads-page-margin

Default page margin.

2.5cm

:root[data-pagenums]

Enables counted page types (see below).

cover, title, toc, body

adoc Studio writes the attributes data-media and data-pagenums automatically into the <body> element. Rules can therefore target these precisely without additional classes.

Named Page Types

A predefined page type exists for each section of the document. It can be addressed in @page rules and styled individually.

Page Type Used for … Counted?

Page Type	Used for …	Counted?
`front-cover`, `front-cover-counted`	Front cover (attr. `:front-cover-image:`)	only *-counted
`title`, `title-counted`	Title page (attr. `:title-page:`)	only *-counted
`toc`, `toc-counted`	Table of contents (when not part of the preamble)	only *-counted
`preamble`, `preamble-counted`	Preamble incl. TOC (when `:toc: preamble`)	only *-counted
`body`, `body-counted`	Main content	only *-counted
`back-cover`	Back cover (attr. `:back-cover-image:`)	no

front-cover, front-cover-counted

Front cover (attr. :front-cover-image:)

only *-counted

title, title-counted

Title page (attr. :title-page:)

only *-counted

toc, toc-counted

Table of contents (when not part of the preamble)

only *-counted

preamble, preamble-counted

Preamble incl. TOC (when :toc: preamble)

only *-counted

body, body-counted

Main content

only *-counted

back-cover

Back cover (attr. :back-cover-image:)

no

More details about page types are available as comments in the base style Base.adocstyle.

Headers and Footers

Document title and chapter name are stored as CSS strings:

h1 { string-set: doctitle content(text); }
h2 { string-set: section1-title content(text); }

The strings can be output in any @page regions:

@page body:left {
    @top-right   { content: string(doctitle); }
    @bottom-right{ content: string(section1-title, first); }
}

Page Counters

A shared counter counted-page runs across all *-counted types:

@page body-counted { counter-increment: counted-page; }
@page body-counted:right {
@bottom-right { content: counter(counted-page); }

This allows you to create numeric running heads or an automatically populated TOC:

.tocbase a::after {
    content: leader('.') target-counter(attr(href), counted-page);

Background Images and Color Areas

Variable Application Fallback

Variable	Application	Fallback
`--ads-front-cover`	Front cover	none
`--ads-back-cover`	Back cover	none
`--ads-page-background-recto`	All right-hand pages	`--ads-page-background`
`--ads-page-background-verso`	All left-hand pages	`--ads-page-background`
`--ads-title-page-background`	Title page	Recto background

--ads-front-cover

Front cover

none

--ads-back-cover

Back cover

none

--ads-page-background-recto

All right-hand pages

--ads-page-background

--ads-page-background-verso

All left-hand pages

--ads-page-background

--ads-title-page-background

Title page

Recto background

Only set the variables that are actually needed. Unset values automatically inherit the fallback.

Footnotes

Vivliostyle supports true paginated footnotes:

span.footnote  { float: footnote; counter-increment: footnote; }
span.footnote::footnote-call   { content: counter(footnote); }
span.footnote::footnote-marker { content: counter(footnote) "."; }

References to existing footnotes receive the counter of the target note:

span.footnoteref::before {
    content: target-counter(attr(data-target), footnote);
}

Best Practices

Define all PDF rules only in @media vivliostyle, never in @media print.
Work with CSS variables instead of fixed values.
Use clearly named page types to assign layout rules precisely.
Test intermediate results in the Vivliostyle preview before starting the final PDF export.

5.7. Embedding Custom Fonts

Copy all font files (recommended: woff2 > woff > ttf) into a fonts/ subfolder of your style.
Declare each variant explicitly:

@font-face {
font-family: "My Custom Font";
src: url("fonts/MyFont-Regular.woff2") format("woff2"),
url("fonts/MyFont-Regular.woff")  format("woff");
font-weight: 400;
font-style:  normal;
font-display: swap;   /* Text remains visible until the font loads */
}

@font-face {
font-family: "My Custom Font";
src: url("fonts/MyFont-Bold.woff2") format("woff2"),
url("fonts/MyFont-Bold.woff")  format("woff");
font-weight: 700;
font-style:  normal;
font-display: swap;
}

:root {
    --ads-body-font: "My Custom Font", serif;
    --ads-headline-font: "My Custom Font", sans-serif;
}

Always check the license before embedding.

macOS / Safari Specifics

Safari 13+ hides user-installed fonts for privacy reasons when "Prevent cross-site tracking" is active. Only core system and Microsoft fonts remain visible. CSS fonts embedded via @font-face work as expected.

Practical implications:

Never rely on locally installed fonts (e.g., Helvetica). Embed every required font explicitly.
For pure system font stacks, use a wide fallback chain, e.g.:

font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text",
"Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;

PDF export: Since Vivliostyle renders the HTML, embedded fonts are reliably included in the PDF file, even if Safari blocks them in the browser.

Web Fonts (Google Fonts and others)

Self-host instead of CDN: For online publications in Germany, using Google servers without opt-in consent can result in legal warnings.

Import the files locally as shown above, or via relative path:

@import url("fonts/inter.css");   /* locally saved CSS file */

If an external CDN is unavoidable:

@import url("[https://fonts.googleapis.com/css2?family=Inter\:wght@300;400;500;700\&display=swap](https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;700&display=swap)");
:root {
    --ads-body-font: "Inter", -apple-system, system-ui, sans-serif;
   --ads-headline-font: "Inter", -apple-system, system-ui, sans-serif;
}

Activate a consent banner or load fonts only after consent to minimize privacy risks.

Troubleshooting Checklist

Font files present in the package and paths correct?
Font weights (font-weight) match the values used?
Safari not showing the font? → @font-face really embedded, clear cache.
PDF exported but font missing? → Check whether file names contain special characters.

With these guidelines, you can embed fonts safely and cross-platform, without relying on system-specific installations.

5.8. Tips and Tricks

Browser DevTools for Live Testing

Open your HTML export in a browser and use the developer tools:

Right-click on an element → "Inspect Element"
Edit rules live in the CSS panel
Test changes directly without recompiling
Copy working rules into your stylesheet

Use Ctrl+Shift+C (Windows) or Cmd+Shift+C (Mac) for the element inspector.

Cache-Busting Strategies

When changes are not visible:

Hard refresh in browser: Ctrl+F5 or Cmd+Shift+R
Clear browser cache
In adoc Studio: Close and reopen the project
Reset stylesheet cache in adoc Studio

Common Pitfalls

Excessive Use of !important

/* Bad */
.my-class {
    color: red !important;
    font-size: 16px !important;
}

/* Better */
.my-class {
    color: red;
    font-size: 16px;
}

/* Or more specific */
.content .my-class {
    color: red;
    font-size: 16px;
}

Missing Dark Mode Contrast

/* Problematic — light mode only */
.warning {
    background-color: #ffff99;
    color: #000000;
}

/* Correct — both modes */
.warning {
    background-color: #ffff99;
    color: #000000;
}

@media (prefers-color-scheme: dark) {
    .warning {
        background-color: #666600;
        color: #ffffff;
    }
}

Variable Scope Issues

/* Wrong — variable not defined */
.element {
    color: var(--undefined-variable);
}

/* Correct — with fallback */
.element {
    color: var(--ads-custom-color, #000000);
}

/* Or define the variable */
:root {
    --ads-custom-color: #cc0000;
}

5.9. Best Practices and Pre-Release Checklist

Consistent Naming

Follow the adoc Studio naming scheme:

/* Good */
--ads-primary-color
--ads-sidebar-width
--ads-button-background-color

/* Bad */
--my-color
--primaryColor
--sidebar_width

Variables Instead of Hard-Coded Values

/* Bad */
.button {
    background-color: #3366cc;
    color: #ffffff;
    border: 1px solid #2255aa;
}

/* Good */
:root {
    --ads-button-bg: #3366cc;
    --ads-button-color: #ffffff;
    --ads-button-border: #2255aa;
}

.button {
    background-color: var(--ads-button-bg);
    color: var(--ads-button-color);
    border: 1px solid var(--ads-button-border);
}

DRY Principle (Don’t Repeat Yourself)

/* Bad — repetition */
.button-primary {
    padding: 0.5em 1em;
    border-radius: 4px;
    font-weight: 500;
    background-color: #3366cc;
}

.button-secondary {
    padding: 0.5em 1em;
    border-radius: 4px;
    font-weight: 500;
    background-color: #666666;
}

/* Good — shared base */
.button {
    padding: 0.5em 1em;
    border-radius: 4px;
    font-weight: 500;
    border: none;
    cursor: pointer;
}

.button-primary {
    background-color: var(--ads-primary-color);
    color: white;
}

.button-secondary {
    background-color: var(--ads-secondary-color);
    color: white;
}

5.10. Pre-Release Checklist

All CSS variables defined with the --ads- prefix
Dark mode variants available for all colors
PDF-specific rules defined with @media vivliostyle
All admonition types styled (note, tip, warning, caution, important)
Table variants tested (stripes, grid, frame)
List types working (ul, ol, checklist, definition)
Code blocks and syntax highlighting verified
Responsive behavior tested on various screen sizes
Contrast checked for accessibility (WCAG 2.1 AA)
Browser compatibility tested
info.json fully completed
License information correct
Documentation and examples created

5.11. Further Resources

5.12. Documentation

5.13. Tools and Validators

Stylelint - CSS Linter
WAVE - Accessibility Evaluator
Contrast Ratio Checker
W3C Markup Validator

5.14. CSS Variables Reference

Here is an overview of the most important CSS variables in adoc Studio:

Typography Variables

--ads-body-font                    /* Body font for text */
--ads-headline-font                /* Font for headings */
--ads-monospaced-font              /* Font for code */
--ads-toc-font                     /* Font for table of contents */
--ads-quote-font                   /* Font for quotations */

Color Variables

/* Basic Colors */
--ads-color                        /* Text color */
--ads-color-dark                   /* Text color (Dark Mode) */
--ads-background-color             /* Background color */
--ads-background-color-dark        /* Background color (Dark Mode) */

/* Headings */
--ads-headline-color               /* Heading color */
--ads-headline-color-dark          /* Heading color (Dark Mode) */
--ads-headline-block-color         /* Block headings */
--ads-headline-small-color         /* Small headings */

/* Links */
--ads-a-color                      /* Link color */
--ads-a-color-dark                 /* Link color (Dark Mode) */
--ads-a-hover-color                /* Hover link color */
--ads-a-hover-color-dark           /* Hover link color (Dark Mode) */

/* Borders */
--ads-single-border-color          /* Simple borders */
--ads-border-color                 /* Transparent borders */
--ads-border-color-dark            /* Transparent borders (Dark Mode) */

Table Variables

--ads-table-background-color       /* Table background */
--ads-table-background-color-dark  /* Table background (Dark Mode) */
--ads-table-head-background-color  /* Header row background */
--ads-table-stripes-background-color /* Striped rows */
--ads-table-border-color           /* Table border */

Admonition Variables

/* Note */
--ads-note-color                   /* Text and icon color */
--ads-note-border-color            /* Border color */
--ads-note-background-color        /* Background color */

/* Tip */
--ads-tip-color
--ads-tip-border-color
--ads-tip-background-color

/* Warning */
--ads-warning-color
--ads-warning-border-color
--ads-warning-background-color

/* Caution */
--ads-caution-color
--ads-caution-border-color
--ads-caution-background-color

/* Important */
--ads-important-color
--ads-important-border-color
--ads-important-background-color

Code Block Variables

--ads-code-color                   /* Code text color */
--ads-code-color-dark              /* Code text color (Dark Mode) */
--ads-pre-background-color         /* Code block background */
--ads-pre-background-color-dark    /* Code block background (Dark Mode) */
--ads-listingblock-background-color /* Listing block background */

/* Syntax Highlighting */
--ads-code-keyword-color           /* Keywords */
--ads-code-string-color            /* Strings */
--ads-code-comment-color           /* Comments */
--ads-code-function-color          /* Functions */
--ads-code-variable-color          /* Variables */

A complete list of all available variables can be found in the base.css of your adoc Studio package.

With this comprehensive guide, you can create and customize professional stylesheets for adoc Studio. Experiment with different approaches and use the provided examples as a starting point for your own designs.

5. Styling with CSS

5.1. Prerequisites

5.2. Basics

Style Categories in adoc Studio

Viewing Factory Styles

Viewing Custom Styles

File Structure of a Style Package

5.3. Creating Custom Styles (3 Approaches)

Duplicate and Adapt a Base Style (recommended for CSS beginners)

External CSS File via Document Attribute

Style from Scratch (for CSS professionals)

5.4. Variable Concepts

Global Color and Typography Variables

Dark Mode Overrides

5.5. Element Classes

Typography

Body and Body Text

Headings

Inline Formatting

Tables

Images and Image Blocks

Lists and Checklists

Code and Syntax Highlighting

Admonitions

Navigation and Table of Contents

Using Custom Classes

Colors

Float and Alignment

5.6. PDF Output with Vivliostyle

Purpose and Function

Global Control

Named Page Types

Headers and Footers

Page Counters

Background Images and Color Areas

Footnotes

Best Practices

5.7. Embedding Custom Fonts

macOS / Safari Specifics

Web Fonts (Google Fonts and others)

Troubleshooting Checklist

5.8. Tips and Tricks

Browser DevTools for Live Testing

Cache-Busting Strategies

Common Pitfalls

Excessive Use of !important

Missing Dark Mode Contrast

Variable Scope Issues

5.9. Best Practices and Pre-Release Checklist

Consistent Naming

Variables Instead of Hard-Coded Values

DRY Principle (Don’t Repeat Yourself)

5.10. Pre-Release Checklist

5.11. Further Resources

5.12. Documentation

5.13. Tools and Validators

5.14. CSS Variables Reference

Typography Variables

Color Variables

Table Variables

Admonition Variables

Code Block Variables