Styles in CSS | Working with adoc Studio

8.1. Prerequisites

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

Please understand that we cannot provide a complete CSS course in this document. If you already know CSS, researching on the internet should not be a problem for you. If you are not technically experienced, please seek external help. We are currently building a partner program that you can contact if interested.

8.2. Basics

You will find all styles under adoc Studio Settings… Product Styles. Alternatively, access the settings with ⌘+,.

Style Categories in adoc Studio

We distinguish between factory styles and custom ones.

Factory Styles: Read-only standard designs, delivered with adoc Studio.
Custom Styles: Duplicated, newly created, or externally imported styles by the user. Custom styles always appear above the Factory Styles in their own group.

default style.en

Right-click on a style and it becomes the default. New projects automatically start with this style.

Viewing Factory Styles

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

You will find the Factory Styles under Contents Resources Factory Styles. Show the package contents here as well to see the info.json and style.css files of the selected style.

Viewing Custom Styles

You have 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 next to the eye symbol in the toolbar.

Select your style. Right-click to open it in Finder or edit it in your text editor of choice.

Now you can show the package contents of the desired .adocstyle 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/Styles creates a symbolic link to the required directory.

File Structure of a Style Package

The style file is a so-called Bundle - a directory displayed as a file. This is a common approach in macOS to simplify handling of collected files.

Click Show Package Contents in Finder to open the file like a folder. The root directory contains the 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 schema `--ads-*`.

info.json

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

resources/style.css

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

The info.json file is a description file where 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 base style
"isHidden": false,                         // true hides the style in menu
}

Note about ID: adoc Studio addresses the style via the ID. If you duplicated a style file from another style, you will find a UUID here that you don’t need to edit. However, you can also use your own identifier as in the example: "id": "app.adoc-studio.style.example"

Beyond this, a style can contain arbitrary content, such as fonts or images used in the style.

A complex example:

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

In the CSS file, you call individual components with the bundle as root directory. The path to a font file would therefore be fonts/font1.ttf.

8.3. Creating Custom Styles (3 Ways)

Duplicate and Adapt 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 necessary.
Include the file in the document:

:stylesheet: custom-style.css

adoc Studio will then use exclusively this stylesheet.

Style from Scratch (for CSS professionals)

Copy an empty Custom Style in Finder.
Delete the contents of style.css and info.json.
Define all needed 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;
}

8.4. Variable Concepts

To provide a common foundation for formatting, we took the standard style from Asciidoctor as a base and derived our factory styles from it.

This allowed us to place all fonts and colors in a long list of variables. Since these are usually the first changes on the wish list, we show you these changes in this document.

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;
    
    /* Base colors */
    --ads-color: #101010;
    --ads-background-color: #ffffff;
    --ads-headline-color: #ba3925;
    
    /* Links */
    --ads-a-color: #2156a5;
    --ads-a-hover-color: #1d4b8f;
    
    /* Borders and boundaries */
    --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);
    }
}

Find a complete list of variables in adoc Studio in here.

8.5. Element Classes

Typography

Body and Base 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

/* Base 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 larger font.

This is a normal 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, centering
`.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, centering

.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 text	`font-weight: bold`
`em`, `i`	Italic	`font-style: italic`
`mark`	Highlighting	`background-color`, `padding`
`code`	Inline code	`font-family: monospace`, `background-color`

strong, b

Bold text

font-weight: bold

em, i

Italic

font-style: italic

mark

Highlighting

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	Alternating `background-color`
`table.frame-all`	Complete frame	`border-width: 1px`
`table.grid-all > * > tr > *`	Complete 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

Alternating background-color

table.frame-all

Complete frame

border-width: 1px

table.grid-all > * > tr > *

Complete 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 Imageblocks

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 display

.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 display

.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 point
Second point
- Sub-point
- Another sub-point

Task 1
Task 2 (completed)
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";
    return variable;
}

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

Admonitions

Class Purpose Typical Rules

Class	Purpose	Typical Rules
`.admonitionblock`	Container for admonitions	`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

Container for admonitions

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.

Attention, caution is required here!

Be especially careful.

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 Centering

.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;
}

8.6. PDF Output with Vivliostyle

8.7. Purpose and Operation

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 encapsulated in their own block:

@media vivliostyle { … }

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

Global Control

Element Task Typical Value

Element	Task	Typical Value
`--ads-page-size`	Transfers the set page size to the print dialog.	`A4 portrait`
`--ads-page-margin`	Standard page margin.	`2.5cm`
`:root[data-pagenums]`	Activates counted page types (see below).	`cover`, `title`, `toc`, `body`

--ads-page-size

Transfers the set page size to the print dialog.

A4 portrait

--ads-page-margin

Standard page margin.

2.5cm

:root[data-pagenums]

Activates counted page types (see below).

cover, title, toc, body

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

Named Page Types

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

Page Type Used for … Counts?

Page Type	Used for …	Counts?
`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 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 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

Find more details about page types as comments in the base style Base.adocstyle.

Headers and Footers

Document title and chapter name are cached via CSS string:

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

The strings can be output in arbitrary @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 creating numerical running heads or an automatically filled TOC:

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

Background Images and Color Areas

Variable Use Case Fallback

Variable	Use Case	Fallback
`--ads-front-cover`	Front cover	none
`--ads-back-cover`	Back cover	none
`--ads-page-background-recto`	All right pages	`--ads-page-background`
`--ads-page-background-verso`	All left 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 pages

--ads-page-background

--ads-page-background-verso

All left pages

--ads-page-background

--ads-title-page-background

Title page

Recto background

Only assign 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 already existing footnotes receive the counter of the target note:

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

8.8. 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.

8.9. Embedding Custom Fonts

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

@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 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 installed user fonts for privacy reasons as soon as "Prevent cross-site tracking" is active. Only core system and Microsoft fonts remain visible. CSS fonts embedded via @font-face work as usual.

Practical consequences:

Never rely on locally installed fonts (e.g., Helvetica). Explicitly embed any needed font.
Use a broad fallback chain for pure system stacks, 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 transferred to the PDF file, even if Safari blocks them in the browser.

Web Fonts (Google Fonts & Co.)

Self-host instead of CDN: For online publication, warnings threaten in Germany if Google servers are contacted without opt-in.

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

@import url("fonts/inter.css");   /* self-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");
: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 package and paths correct?
Font weights (font-weight) match the used values?
Safari doesn’t show the font? → @font-face really embedded, clear cache.
PDF exported but font missing? → Check if filenames contain special characters.

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

8.10. 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"
In the CSS panel, you can edit rules live
Test changes directly without recompilation
Copy working rules into your stylesheet

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

Cache-Bust Strategies

When changes don’t become visible:

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

Common Pitfalls

Excessive !important Usage

/* 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 Contrasts

/* Problematic - only light mode */
.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 Problems

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

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

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

8.11. 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-Codes

/* 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;
}

Pre-Release Checklist

All CSS variables defined with --ads- prefix
Dark mode variants present 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 functional (ul, ol, checklist, definition)
Code blocks and syntax highlighting verified
Responsive behavior tested on various screen sizes
Contrasts checked for accessibility (WCAG 2.1 AA)
Browser compatibility tested
info.json completely filled out
License information correct
Documentation and examples created

8.12. Further Resources

Documentation

Tools and Validators

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

8.13. CSS Variables Reference

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

Typography Variables

--ads-body-font                    /* Base 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 quotes */

Color Variables

/* Base 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 background */
--ads-table-stripes-background-color /* Striped rows */
--ads-table-border-color           /* Table borders */

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 */

Find a complete list of all available variables 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 starting points for your own designs.

8. Styles in CSS

8.1. Prerequisites

8.2. Basics

Style Categories in adoc Studio

Viewing Factory Styles

Viewing Custom Styles

File Structure of a Style Package

8.3. Creating Custom Styles (3 Ways)

Duplicate and Adapt Base Style (recommended for CSS beginners)

External CSS File via Document Attribute

Style from Scratch (for CSS professionals)

8.4. Variable Concepts

Global Color and Typography Variables

Dark Mode Overrides

8.5. Element Classes

Typography

Body and Base Text

Headings

Inline Formatting

Tables

Images and Imageblocks

Lists and Checklists

Code and Syntax Highlighting

Admonitions

Navigation and Table of Contents

Using Custom Classes

Colors

Float and Centering

8.6. PDF Output with Vivliostyle

8.7. Purpose and Operation

Global Control

Named Page Types

Headers and Footers

Page Counters

Background Images and Color Areas

Footnotes

8.8. Best Practices

8.9. Embedding Custom Fonts

macOS / Safari Specifics

Web Fonts (Google Fonts & Co.)

Troubleshooting Checklist

8.10. Tips and Tricks

Browser DevTools for Live Testing

Cache-Bust Strategies

Common Pitfalls

Excessive !important Usage

Missing Dark Mode Contrasts

Variable Scope Problems

8.11. Best Practices and Pre-Release Checklist

Consistent Naming

Variables Instead of Hard-Codes

DRY Principle (Don’t Repeat Yourself)

Pre-Release Checklist

8.12. Further Resources

Documentation

Tools and Validators

8.13. CSS Variables Reference

Typography Variables

Color Variables

Table Variables

Admonition Variables

Code Block Variables