Gestaltung mit CSS | Arbeiten mit adoc Studio

5.1. Voraussetzungen

adoc Studio
Texteditor oder IDE mit CSS-Support
Browser mit Entwicklertools für Tests

Bitte haben Sie Verständnis, dass wir in diesem Dokument keinen CSS-Kurs anbieten können. Sollten Sie sich mit CSS bereits auskennen, ist die Recherche im Internet für Sie sicher kein Problem. Sind Sie nicht technisch bewandert, holen Sie sich gerne Hilfe von außen. Wir bauen zur Zeit ein Partnerprogramm, an das Sie sich bei Interesse gerne wenden können.

5.2. Grundlagen

Sie finden alle Stile unter adoc Studio Einstellungen… Produkt-Stile. Alternativ gelangen sie mit ⌘+, in die Einstellungen.

Stil-Kategorien in adoc Studio

Wir unterscheiden zwischen mitgelieferten und eigenen Stilen.

Mitgelieferte Stile (Factory Styles): Schreibgeschützte Standarddesigns, die in adoc Studio enthalten sind.
Eigene Stile: Vom Nutzer duplizierte, neu angelegte oder extern eingebundene Stile. Eigene Stile erscheinen immer oberhalb der FactoryStyles in einer eigenen Gruppe.

default style.de

Rechtsklick auf einen Stil – und schon ist er als Standard gesetzt. Neue Projekte starten automatisch mit diesem Stil.

Mitgelieferte Stile ansehen

Mit Rechtsklick auf adoc Studio in Ihrem Programme-Ordner lassen Sie sich den Paketinhalt der Software anzeigen.

Die mitgelieferten Stile finden Sie unter Contents Resources FactoryStyles. Lassen Sie sich hier ebenfalls den Paketinhalt anzeigen, um die info.json und die style.css Dateien des ausgewählten Stils zu sehen.

Eigene Stile ansehen

Es gibt zwei Wege, wie Sie Ihre eigenen Stile ansehen können:

Im Finder: Eigene Stile werden unter Library Containers app.adoc-studio.main Data Library Application Support Styles gespeichert.
In adoc Studio: Klicken Sie auf den Pfeil neben dem -Symbol in der Symbolleiste. Wählen Sie Ihren Stil im Popup aus.

Mit Rechtsklick öffnen Sie ihn im Finder oder bearbeiten ihn im Text-Editor Ihrer Wahl.

Nun können Sie bei der gewünschten .adocstyle wieder den Paketinhalt anzeigen lassen (siehe oben für die Erklärung)

Verwalten Sie Ihre Dateien in einem Git Repository, können Sie auch Ihre Produktstile dort versionieren.
ln -s path/to/your/repository ~/Library/Containers/app.adoc-studio.main/Data/Library/Application Support erzeugt einen symbolischen Link in das erforderliche Verzeichnis.
Wichtig ist dann auch noch, dass in adoc Studio in den Einstellungen der Zugriff auf das Verzeichnis gestattet ist.

Dateistruktur eines Stil-Pakets

Die Stildatei ist ein sogenanntes Bundle – also ein Verzeichnis, das als Datei dargestellt wird. Das ist im macOS ein üblichen Vorgehen, um den Umgang mit den gesammelten Dateien zu vereinfachen.

Klicken Sie im Finder auf Paketinhalt anzeigen, öffnet sich die Datei wie ein Ordner. Im Stammverzeichnis liegt die info.json; daneben ein Ordner resources, der sämtliche Assets bündelt.

Die minimale Struktur ist:

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

Datei Inhalt

Datei	Inhalt
`info.json`	Metadaten (ID, Anzeigename, Option `basedOn` usw.).
`resources/style.css`	Alle CSS-Regeln. Nutzt das Variablenschema `--ads-*`.

info.json

Metadaten (ID, Anzeigename, Option basedOn usw.).

resources/style.css

Alle CSS-Regeln. Nutzt das Variablenschema --ads-*.

Die Datei info.json ist eine Beschreibungsdatei in der Sie das Grundverhalten Ihres Stils festlegen.

Beispiel info.json mit Erklärung

{
"id": "app.adoc-studio.style.beispiel",    // eindeutige interne Kennung
"name": "Beispiel",                        // Anzeigename in adoc Studio
"basedOn": "app.adoc-studio.style.base",   // optional: ID des Basisstils
"isHidden": false,                         // true blendet den Stil im Menü aus
}

Nachtrag zur ID: Über die ID spricht adoc Studio den Stil an. Haben Sie eine Stildatei von einem anderen Stil dupliziert, finden Sie hier eine UUID, die Sie nicht bearbeiten müssen. Sie können aber auch einen eigenen Identifier wie im Beispiel nutzen: "id": "app.adoc-studio.style.beispiel"

Darüber hinaus kann ein Stil beliebige Inhalte, wie Fonts oder Bilder enthalten, die im Stil verwendet werden.

Ein komplexes Beispiel:

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

In der CSS-Datei rufen Sie einzelne Bestandteile mit dem Bundle als Wurzelverzeichnis. Der Pfad zu einer Font-Datei lautet also fonts/font1.ttf.

5.3. Eigene Stile erstellen (3 Wege)

Basisstil duplizieren und anpassen (empfohlen für CSS Einsteiger)

Öffnen Sie Einstellungen oder klicken Sie in den Vorschau-Einstellungen auf menu:…[Stil bearbeiten].
Wählen Sie einen Basisstil und klicken Sie Duplizieren.
Öffnen Sie den neuen Stil per Im Finder anzeigen → Paketinhalt anzeigen.
Bearbeiten Sie style.css in Ihrem Editor.

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

Externe CSS-Datei per Dokumentattribut

Legen Sie im Projektordner custom-style.css an.
Entfernen Sie ggf. automatisch gesetzte Titelzeilen.
Binden Sie die Datei im Dokument ein:

:stylesheet: custom-style.css

adoc Studio verwendet dann ausschließlich dieses Stylesheet.

Stil von Grund auf neu (für CSS-Profis)

Kopieren Sie einen leeren Custom Style im Finder.
Löschen Sie den Inhalt von style.css und info.json.
Definieren Sie alle benötigten Variablen selbst:

: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-Konzepte

Damit es eine gemeinsame Grundlage für die Formatierung gibt, haben wir den Standard-Stil von Asciidoctor als Basis genommen und unsere mitgelieferten Stile davon abgeleitet.

So konnten wir alle Fonts und Farben in einer langen Liste von Variablen ablegen. Da das meistens die ersten Änderungen auf der Wunschliste sind, zeigen wir Ihnen in diesem Dokument diese Änderungen.

adoc Studio verwendet ein strukturiertes System von CSS-Variablen mit dem Präfix --ads-.

Globale Farb- und Typografie-Variablen

Die wichtigsten Variablen-Kategorien:

:root {
    /* Typografie */
    --ads-body-font: serif;
    --ads-headline-font: sans-serif;
    --ads-monospaced-font: monospace;
    --ads-toc-font: sans-serif;
    
    /* Grundfarben */
    --ads-color: #101010;
    --ads-background-color: #ffffff;
    --ads-headline-color: #ba3925;
    
    /* Links */
    --ads-a-color: #2156a5;
    --ads-a-hover-color: #1d4b8f;
    
    /* Rahmen und Grenzen */
    --ads-single-border-color: #dddddf;
    --ads-border-color: rgb(0 0 0 / 0.6);
}

Dark-Mode-Overrides

Definieren Sie separate Variablen für den 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);
    }
}

Eine vollständige Liste der Variablen in adoc Studio finden Sie in hier.

5.5. Element-Klassen

Typografie

Body und Grundtext

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`.paragraph > p`	Absätze	`font-size`, `line-height`, `margin-bottom`
`.paragraph.lead > p`	Präambel	Größere Schrift, `font-weight: 500`
`#preamble > .sectionbody > [class=paragraph]:first-of-type p`	Erster Absatz	Spezielle Formatierung für Einleitung

.paragraph > p

Absätze

font-size, line-height, margin-bottom

.paragraph.lead > p

Präambel

Größere Schrift, font-weight: 500

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

Erster Absatz

Spezielle Formatierung für Einleitung

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

Beispiel in AsciiDoc:

Dies ist ein Einleitungstext mit größerer Schrift.

Dies ist ein normaler Absatz mit Standardformatierung.

Überschriften

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`h1`, `h2`, `h3`, `h4`, `h5`, `h6`	Überschriften	`font-family`, `font-weight`, `color`, `margin`
`#header > h1:first-child`	Dokumenttitel	Größere Schrift, Zentrierung
`.subtitle`	Untertitel	Kleinere Schrift als Haupttitel

h1, h2, h3, h4, h5, h6

Überschriften

font-family, font-weight, color, margin

#header > h1:first-child

Dokumenttitel

Größere Schrift, Zentrierung

.subtitle

Untertitel

Kleinere Schrift als Haupttitel

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-Formatierung

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`strong`, `b`	Fettschrift	`font-weight: bold`
`em`, `i`	Kursiv	`font-style: italic`
`mark`	Markierung	`background-color`, `padding`
`code`	Inline-Code	`font-family: monospace`, `background-color`

strong, b

Fettschrift

font-weight: bold

em, i

Kursiv

font-style: italic

mark

Markierung

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

Tabellen

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`table.tableblock`	Grundtabelle	`border-collapse`, `background-color`
`table thead th`	Tabellenkopf	`background-color`, `font-weight`
`table.stripes-all > * > tr`	Gestreifte Zeilen	`background-color` alternierend
`table.frame-all`	Vollständiger Rahmen	`border-width: 1px`
`table.grid-all > * > tr > *`	Vollständiges Raster	Alle Zellenränder

table.tableblock

Grundtabelle

border-collapse, background-color

table thead th

Tabellenkopf

background-color, font-weight

table.stripes-all > * > tr

Gestreifte Zeilen

background-color alternierend

table.frame-all

Vollständiger Rahmen

border-width: 1px

table.grid-all > * > tr > *

Vollständiges Raster

Alle Zellenränder

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

Beispiel in AsciiDoc:

Name	Beschreibung	Status
Feature A	Wichtige Funktionalität	Aktiv
Feature B	Zusätzliche Option	Beta

Name

Beschreibung

Status

Feature A

Wichtige Funktionalität

Aktiv

Feature B

Zusätzliche Option

Beta

Bilder und Imageblocks

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`.imageblock`	Bildcontainer	`margin`, `text-align`
`.imageblock > .title`	Bildunterschrift	`font-size`, `font-style`
`.imageblock.left`	Linksbündiges Bild	`float: left`, `margin-right`
`.imageblock.right`	Rechtsbündiges Bild	`float: right`, `margin-left`
`img`	Bild-Element	`max-width: 100%`, `height: auto`

.imageblock

Bildcontainer

margin, text-align

.imageblock > .title

Bildunterschrift

font-size, font-style

.imageblock.left

Linksbündiges Bild

float: left, margin-right

.imageblock.right

Rechtsbündiges Bild

float: right, margin-left

img

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

Beispiel in AsciiDoc:

.Beispielbild mit Beschriftung
image::beispiel.png[alt="Beispiel", width=400]

[.left]
.Linksbündiges Bild
image::logo.png[alt="Logo", width=200]

Listen und Checklisten

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`.ulist ul`	Ungeordnete Liste	`list-style-type`, `margin`
`.olist ol`	Geordnete Liste	`list-style-type: decimal`
`.checklist ul`	Checkliste	`list-style-type: none`
`.dlist`	Definitionsliste	Spezielle Formatierung für Begriff/Definition
`.hdlist`	Horizontale Definitionsliste	Tabellenähnliche Darstellung

.ulist ul

Ungeordnete Liste

list-style-type, margin

.olist ol

Geordnete Liste

list-style-type: decimal

.checklist ul

Checkliste

list-style-type: none

.dlist

Definitionsliste

Spezielle Formatierung für Begriff/Definition

.hdlist

Horizontale Definitionsliste

Tabellenähnliche Darstellung

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

Beispiel in AsciiDoc:

Erster Punkt
Zweiter Punkt
- Unterpunkt
- Weiterer Unterpunkt

Aufgabe 1
Aufgabe 2 (erledigt)
Aufgabe 3

Begriff

Definition des Begriffs

Anderer Begriff

Weitere Definition

Code und Syntax-Highlighting

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`.listingblock`	Code-Block-Container	`background-color`, `border-radius`
`.listingblock > .content > pre`	Code-Inhalt	`font-family: monospace`, `overflow-x`
`.code-keyword`	Schlüsselwörter	`color`, `font-weight: bold`
`.code-string`	Zeichenketten	`color` (meist grün oder blau)
`.code-comment`	Kommentare	`color` (meist grau), `font-style: italic`

.listingblock

Code-Block-Container

background-color, border-radius

.listingblock > .content > pre

Code-Inhalt

font-family: monospace, overflow-x

.code-keyword

Schlüsselwörter

color, font-weight: bold

.code-string

Zeichenketten

color (meist grün oder blau)

.code-comment

Kommentare

color (meist grau), 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);
}

Beispiel in AsciiDoc:

function beispielFunktion() {
    // Dies ist ein Kommentar
    const variable = "Zeichenkette";
    return variable;
}

.beispiel-klasse {
    color: red;
    font-size: 1.2em;
    }

Hinweise (Admonitions)

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`.admonitionblock`	Container für Hinweise	`margin`, `border`, `background-color`
`.admonitionblock.note`	Hinweis (blau)	Blaue Farben
`.admonitionblock.tip`	Tipp (grün)	Grüne Farben
`.admonitionblock.warning`	Warnung (orange)	Orange Farben
`.admonitionblock.caution`	Vorsicht (gelb)	Gelbe Farben
`.admonitionblock.important`	Wichtig (rot)	Rote Farben
`.admonitionblock td.icon`	Icon-Bereich	Icon-Formatierung
`.admonitionblock td.content`	Textinhalt	Textformatierung

.admonitionblock

Container für Hinweise

margin, border, background-color

.admonitionblock.note

Hinweis (blau)

Blaue Farben

.admonitionblock.tip

Tipp (grün)

Grüne Farben

.admonitionblock.warning

Warnung (orange)

Orange Farben

.admonitionblock.caution

Vorsicht (gelb)

Gelbe Farben

.admonitionblock.important

Wichtig (rot)

Rote Farben

.admonitionblock td.icon

Icon-Bereich

Icon-Formatierung

.admonitionblock td.content

Textinhalt

Textformatierung

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

Beispiel in AsciiDoc:

Dies ist ein wichtiger Hinweis für den Leser.

Hier steht ein nützlicher Tipp.

Achtung, hier ist Vorsicht geboten!

Seien Sie besonders vorsichtig.

Dies ist sehr wichtig zu beachten.

Navigation und Inhaltsverzeichnis

Klasse Zweck Typische Regeln

Klasse	Zweck	Typische Regeln
`.tocbase`	TOC-Container	`background-color`, `border`, `padding`
`#toctitle`	TOC-Überschrift	`font-size`, `font-weight`, `color`
`.tocbase ul`	TOC-Listen	`list-style: none`, `margin`
`.tocbase li`	TOC-Einträge	`line-height`, `margin`
`.tocbase a`	TOC-Links	`text-decoration: none`, `color`

.tocbase

TOC-Container

background-color, border, padding

#toctitle

TOC-Überschrift

font-size, font-weight, color

.tocbase ul

TOC-Listen

list-style: none, margin

.tocbase li

TOC-Einträge

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

/* Einrückung für Unterebenen */
.tocbase ul ul {
    padding-left: 1em;
    margin-top: 0.25em;
}

Eigene Klassen verwenden

Sie können eigene Klassen definieren und direkt im Text aktivieren. Setzen Sie dazu den Klassennamen in eckige Klammern ([.custom-class]) vor das entsprechende Element.

Beispiele in AsciiDoc:

Dieser Text ist rot.

Dieser Text ist horizontal zentriert.

Farben

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

/* Hintergrundfarben */
.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 und Zentrierung

.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-Ausgabe mit Vivliostyle

Zweck und Arbeitsweise

Vivliostyle ist eine JavaScript-Engine für CSS Paged Media. adoc Studio nutzt sie, um das HTML‐Preview in ein druckfertiges PDF zu paginieren. Alle PDF-spezifischen Regeln werden deshalb in einem eigenen Block gekapselt:

@media vivliostyle { … }

Innerhalb dieses Blocks gelten die gleichen CSS-Selektoren wie im Browser, ergänzt um paged-media-Eigenschaften wie @page, string-set oder counter-increment.

Globale Steuerung

Element Aufgabe Typischer Wert

Element	Aufgabe	Typischer Wert
`--ads-page-size`	Überträgt die eingestellte Seitengröße an den Print-Dialog.	`A4 portrait`
`--ads-page-margin`	Standard-Seitenrand.	`2.5cm`
`:root[data-pagenums]`	Aktiviert gezählte Seitentypen (siehe unten).	`cover`, `title`, `toc`, `body`

--ads-page-size

Überträgt die eingestellte Seitengröße an den Print-Dialog.

A4 portrait

--ads-page-margin

Standard-Seitenrand.

2.5cm

:root[data-pagenums]

Aktiviert gezählte Seitentypen (siehe unten).

cover, title, toc, body

adoc Studio schreibt die Attribute data-media und data-pagenums automatisch ins <body>‐Element. Regeln können so gezielt greifen, ohne zusätzliche Klassen.

Benannte Seitentypen

Für jeden Abschnitt des Dokuments existiert ein vordefinierter Seitentyp. Er lässt sich in @page-Regeln ansprechen und einzeln gestalten.

Seitentyp Wird verwendet für … Zählt?

Seitentyp	Wird verwendet für …	Zählt?
`front-cover`, `front-cover-counted`	Vorderumschlag (Attr. `:front-cover-image:`)	nur *-counted
`title`, `title-counted`	Titelseite (Attr. `:title-page:`)	nur *-counted
`toc`, `toc-counted`	Inhaltsverzeichnis (wenn nicht Teil der Präambel)	nur *-counted
`preamble`, `preamble-counted`	Präambel inkl. TOC (wenn `:toc: preamble`)	nur *-counted
`body`, `body-counted`	Hauptinhalt	nur *-counted
`back-cover`	Rückumschlag (Attr. `:back-cover-image:`)	nein

front-cover, front-cover-counted

Vorderumschlag (Attr. :front-cover-image:)

nur *-counted

title, title-counted

Titelseite (Attr. :title-page:)

nur *-counted

toc, toc-counted

Inhaltsverzeichnis (wenn nicht Teil der Präambel)

nur *-counted

preamble, preamble-counted

Präambel inkl. TOC (wenn :toc: preamble)

nur *-counted

body, body-counted

Hauptinhalt

nur *-counted

back-cover

Rückumschlag (Attr. :back-cover-image:)

nein

Mehr Details zu den Seitentypen finden Sie als Kommentare im Basis-Stil Base.adocstyle.

Kopf- und Fußzeilen

Dokumenttitel und Kapitelname werden per CSS-String zwischengespeichert:

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

Die Strings lassen sich in beliebigen @page-Regionen ausgeben:

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

Seitenzähler

Ein gemeinsamer Zähler counted-page läuft über alle *-counted-Typen:

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

Damit lassen sich numerische Kolumnentitel oder ein automatisch gefülltes TOC erzeugen:

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

Hintergrundbilder und Farbflächen

Variable Einsatzgebiet Fallback

Variable	Einsatzgebiet	Fallback
`--ads-front-cover`	Vorderumschlag	keiner
`--ads-back-cover`	Rückumschlag	keiner
`--ads-page-background-recto`	Alle rechten Seiten	`--ads-page-background`
`--ads-page-background-verso`	Alle linken Seiten	`--ads-page-background`
`--ads-title-page-background`	Titelseite	Recto-Hintergrund

--ads-front-cover

Vorderumschlag

keiner

--ads-back-cover

Rückumschlag

keiner

--ads-page-background-recto

Alle rechten Seiten

--ads-page-background

--ads-page-background-verso

Alle linken Seiten

--ads-page-background

--ads-title-page-background

Titelseite

Recto-Hintergrund

Vergeben Sie nur die Variablen, die tatsächlich benötigt sind. Nicht gesetzte Werte erben automatisch den Fallback.

Fußnoten

Vivliostyle unterstützt echte paginierte Fußnoten:

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

Referenzen auf bereits vorhandene Fußnoten erhalten den Zähler der Zielnote:

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

Best Practices

Definieren Sie alle PDF-Regeln nur in @media vivliostyle, nie in @media print.
Arbeiten Sie mit CSS-Variablen statt festen Werten.
Verwenden Sie klar benannte Seitentypen, um Layoutregeln präzise zuzuweisen.
Testen Sie Zwischenergebnisse im Vivliostyle-Preview, bevor Sie den finalen PDF-Export starten.

5.7. Eigene Fonts einbinden

Kopieren Sie alle Schriftdateien (empfohlen: woff2 > woff > ttf) in einen Unterordner fonts/ Ihres Styles.
Deklarieren Sie jede Schnitte eindeutig:

@font-face {
font-family: "Mein Custom Font";
src: url("fonts/MeinFont-Regular.woff2") format("woff2"),
url("fonts/MeinFont-Regular.woff")  format("woff");
font-weight: 400;
font-style:  normal;
font-display: swap;   /* Text bleibt sichtbar, bis die Font geladen ist */
}

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

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

Prüfen Sie vor dem Einbetten stets die Lizenz.

macOS / Safari-Besonderheiten

Safari 13 + blendet aus Datenschutzgründen installierte Benutzer-Fonts aus, sobald “Websiteübergreifendes Tracking verhindern” aktiv ist. Sichtbar bleiben nur Kernsystem- und Microsoft-Schriften. CSS-Fonts, die per @font-face eingebettet sind, funktionieren hingegen wie gewohnt.

Praktische Folgen:

Verlassen Sie sich nie auf lokal installierte Schriften (z. B. Helvetica). Binden Sie jede benötigte Font explizit ein.
Verwenden Sie für reine System-Stacks eine breite Fallback-Kette, z. B.:

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

PDF-Export: Da Vivliostyle das HTML rendert, werden eingebettete Fonts zuverlässig in die PDF-Datei übernommen, auch wenn Safari sie im Browser blockiert.

Web-Fonts (Google Fonts & Co.)

Selbst hosten statt CDN: Bei Online-Veröffentlichung drohen in Deutschland Abmahnungen, wenn Google-Server ohne Opt-In kontaktiert werden.

Importieren Sie die Dateien lokal wie oben gezeigt oder per relativem Pfad:

@import url("fonts/inter.css");   /* selbst gespeicherte CSS-Datei */

Wenn ein externes CDN unvermeidbar ist:

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

Aktivieren Sie ein Consent-Banner oder laden Sie die Fonts erst nach Zustimmung nach, um Datenschutzrisiken zu minimieren.

Troubleshooting-Checkliste

Font-Dateien im Paket vorhanden und Pfade korrekt?
Schriftgewichte (font-weight) stimmen mit den verwendeten Werten überein?
Safari zeigt die Schrift nicht? → @font-face wirklich eingebettet, Cache leeren.
PDF exportiert, aber Font fehlt? → Prüfen, ob Dateinamen Sonderzeichen enthalten.

Mit diesen Hinweisen binden Sie Fonts sicher und plattformübergreifend ein, ohne auf systemabhängige Installationen zu vertrauen.

5.8. Tipps und Tricks

Browser-DevTools für Live-Tests

Öffnen Sie Ihr HTML-Export in einem Browser und nutzen Sie die Entwicklertools:

Rechtsklick auf ein Element → "Element untersuchen"
Im CSS-Panel können Sie Regeln live bearbeiten
Testen Sie Änderungen direkt ohne Neucompilierung
Kopieren Sie funktionierende Regeln in Ihr Stylesheet

Verwenden Sie Strg+Shift+C (Windows) oder Cmd+Shift+C (Mac) für den Elementinspektor.

Cache-Bust-Strategien

Wenn Änderungen nicht sichtbar werden:

Hard-Refresh im Browser: Strg+F5 oder Cmd+Shift+R
Browser-Cache leeren
In adoc Studio: Projekt schließen und neu öffnen
Stylesheet-Cache in adoc Studio zurücksetzen

Häufige Stolperfallen

Übermäßiger !important-Einsatz

/* Schlecht */
.meine-klasse {
    color: red !important;
    font-size: 16px !important;
}

/* Besser */
.meine-klasse {
    color: red;
    font-size: 16px;
}

/* Oder spezifischer */
.content .meine-klasse {
    color: red;
    font-size: 16px;
}

Fehlende Dark-Mode-Kontraste

/* Problematisch - nur heller Modus */
.warnung {
    background-color: #ffff99;
    color: #000000;
}

/* Korrekt - beide Modi */
.warnung {
    background-color: #ffff99;
    color: #000000;
}

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

Variable-Scope-Probleme

/* Falsch - Variable nicht definiert */
.element {
    color: var(--undefined-variable);
}

/* Korrekt - mit Fallback */
.element {
    color: var(--ads-custom-color, #000000);
}

/* Oder Variable definieren */
:root {
    --ads-custom-color: #cc0000;
}

5.9. Best Practices und Checkliste vor Release

Konsistente Benennung

Befolgen Sie das adoc Studio Namensschema:

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

/* Schlecht */
--my-color
--primaryColor
--sidebar_width

Variablen statt Hard-Codes

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

/* Gut */
: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-Prinzip (Don’t Repeat Yourself)

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

/* Gut - Gemeinsame Basis */
.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. Checkliste vor Release

Alle CSS-Variablen mit --ads- Präfix definiert
Dark-Mode-Varianten für alle Farben vorhanden
PDF-spezifische Regeln mit @media vivliostyle definiert
Alle Admonitions-Typen gestylt (note, tip, warning, caution, important)
Tabellen-Varianten getestet (stripes, grid, frame)
Listen-Typen funktionsfähig (ul, ol, checklist, definition)
Code-Blocks und Syntax-Highlighting überprüft
Responsive Verhalten auf verschiedenen Bildschirmgrößen getestet
Kontraste für Barrierefreiheit überprüft (WCAG 2.1 AA)
Browser-Kompatibilität getestet
info.json vollständig ausgefüllt
Lizenz-Informationen korrekt
Dokumentation und Beispiele erstellt

5.11. Weiterführende Ressourcen

5.12. Dokumentation

5.13. Tools und Validatoren

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

5.14. CSS-Variablen Referenz

Hier ist eine Übersicht der wichtigsten CSS-Variablen in adoc Studio:

Typografie-Variablen

--ads-body-font                    /* Grundschrift für Text */
--ads-headline-font                /* Schrift für Überschriften */
--ads-monospaced-font              /* Schrift für Code */
--ads-toc-font                     /* Schrift für Inhaltsverzeichnis */
--ads-quote-font                   /* Schrift für Zitate */

Farb-Variablen

/* Grundfarben */
--ads-color                        /* Textfarbe */
--ads-color-dark                   /* Textfarbe (Dark Mode) */
--ads-background-color             /* Hintergrundfarbe */
--ads-background-color-dark        /* Hintergrundfarbe (Dark Mode) */

/* Überschriften */
--ads-headline-color               /* Überschriftenfarbe */
--ads-headline-color-dark          /* Überschriftenfarbe (Dark Mode) */
--ads-headline-block-color         /* Block-Überschriften */
--ads-headline-small-color         /* Kleine Überschriften */

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

/* Rahmen */
--ads-single-border-color          /* Einfache Rahmen */
--ads-border-color                 /* Transparente Rahmen */
--ads-border-color-dark            /* Transparente Rahmen (Dark Mode) */

Tabellen-Variablen

--ads-table-background-color       /* Tabellenhintergrund */
--ads-table-background-color-dark  /* Tabellenhintergrund (Dark Mode) */
--ads-table-head-background-color  /* Kopfzeilen-Hintergrund */
--ads-table-stripes-background-color /* Gestreifte Zeilen */
--ads-table-border-color           /* Tabellenrahmen */

Admonitions-Variablen

/* Note (Hinweis) */
--ads-note-color                   /* Text- und Icon-Farbe */
--ads-note-border-color            /* Rahmenfarbe */
--ads-note-background-color        /* Hintergrundfarbe */

/* Tip (Tipp) */
--ads-tip-color
--ads-tip-border-color
--ads-tip-background-color

/* Warning (Warnung) */
--ads-warning-color
--ads-warning-border-color
--ads-warning-background-color

/* Caution (Vorsicht) */
--ads-caution-color
--ads-caution-border-color
--ads-caution-background-color

/* Important (Wichtig) */
--ads-important-color
--ads-important-border-color
--ads-important-background-color

Code-Block-Variablen

--ads-code-color                   /* Code-Textfarbe */
--ads-code-color-dark              /* Code-Textfarbe (Dark Mode) */
--ads-pre-background-color         /* Code-Block-Hintergrund */
--ads-pre-background-color-dark    /* Code-Block-Hintergrund (Dark Mode) */
--ads-listingblock-background-color /* Listing-Block-Hintergrund */

/* Syntax-Highlighting */
--ads-code-keyword-color           /* Schlüsselwörter */
--ads-code-string-color            /* Strings */
--ads-code-comment-color           /* Kommentare */
--ads-code-function-color          /* Funktionen */
--ads-code-variable-color          /* Variablen */

Eine vollständige Liste aller verfügbaren Variablen finden Sie in der base.css Ihres adoc Studio Pakets.

Mit diesem umfassenden Leitfaden können Sie professionelle Stylesheets für adoc Studio erstellen und anpassen. Experimentieren Sie mit verschiedenen Ansätzen und nutzen Sie die bereitgestellten Beispiele als Ausgangspunkt für Ihre eigenen Designs.

5. Gestaltung mit CSS

5.1. Voraussetzungen

5.2. Grundlagen

Stil-Kategorien in adoc Studio

Mitgelieferte Stile ansehen

Eigene Stile ansehen

Dateistruktur eines Stil-Pakets

5.3. Eigene Stile erstellen (3 Wege)

Basisstil duplizieren und anpassen (empfohlen für CSS Einsteiger)

Externe CSS-Datei per Dokumentattribut

Stil von Grund auf neu (für CSS-Profis)

5.4. Variable-Konzepte

Globale Farb- und Typografie-Variablen

Dark-Mode-Overrides

5.5. Element-Klassen

Typografie

Body und Grundtext

Überschriften

Inline-Formatierung

Tabellen

Bilder und Imageblocks

Listen und Checklisten

Code und Syntax-Highlighting

Hinweise (Admonitions)

Navigation und Inhaltsverzeichnis

Eigene Klassen verwenden

Farben

Float und Zentrierung

5.6. PDF-Ausgabe mit Vivliostyle

Zweck und Arbeitsweise

Globale Steuerung

Benannte Seitentypen

Kopf- und Fußzeilen

Seitenzähler

Hintergrundbilder und Farbflächen

Fußnoten

Best Practices

5.7. Eigene Fonts einbinden

macOS / Safari-Besonderheiten

Web-Fonts (Google Fonts & Co.)

Troubleshooting-Checkliste

5.8. Tipps und Tricks

Browser-DevTools für Live-Tests

Cache-Bust-Strategien

Häufige Stolperfallen

Übermäßiger !important-Einsatz

Fehlende Dark-Mode-Kontraste

Variable-Scope-Probleme

5.9. Best Practices und Checkliste vor Release

Konsistente Benennung

Variablen statt Hard-Codes

DRY-Prinzip (Don’t Repeat Yourself)

5.10. Checkliste vor Release

5.11. Weiterführende Ressourcen

5.12. Dokumentation

5.13. Tools und Validatoren

5.14. CSS-Variablen Referenz

Typografie-Variablen

Farb-Variablen

Tabellen-Variablen

Admonitions-Variablen

Code-Block-Variablen