CSS für AsciiDoc in Nikola

Source

Das Problem

Das AsciiDoc-Plugin von Nikola nimmt (Quellcode: https://github.com/getnikola/plugins/blob/master/v7/asciidoc/asciidoc.py) im Prinzip den Seitencode und übergibt ihn mit den Parametern "-b html5 -s -o" an asciidoc bzw. asciidoctor.
Asciidoctor generiert daraus HTML und gibt es an Nikola zurück.

Die Parameter haben dabei folgende Bedeutung:

  • -b → Ausgabeformat (HTML 5 hier)

  • -s → es wird ohne Header und Footer geschrieben

  • -o → wo die Ausgabedatei hingeschrieben wird

Asciidoctor würde normalerweise eine komplette Seite generieren und dort CSS im <header> hinterlegen:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.16">
<title>Fazit</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
html{font-family:sans-serif;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
[…]
</style>
</head>
<body class="article">
<div id="header">
</div>
<div id="content">
<div class="paragraph">
<p>In Python gibt es diese schöne Möglichkeit:</p>
</div>
<div class="listingblock">

Das Flag "-s" verhindert das, weil der HTM-Head-Teil (also alle Meta-Informationen) durch Nikola generiert werden und von AsciiDoctor nur die Konvertierung des Inhalts in HTML gemacht werden soll.
Das macht insofern Sinn, da Nikola eine einheitliche Darstellung über alle Seiten hinweg sicherstellen muss (Theme, die Kopfleiste/Navigation usw.) und die Metadaten der Seite verarbeitet.
Asciidoctor generiert also reines HTML, ohne CSS/Einbindung eigener CSS-Dateien.

<div class="paragraph">
<p>In Python gibt es diese schöne Möglichkeit:</p>
</div>
<div class="listingblock">

Das CSS kommt von Nikola. Das führt zu Problemen wenn man Formatierungen in AcsiiDoc oder Blöcke oder Syntax-Highlighting benutzt. Das CSS von Nikola hat zwar Regeln für alle möglichen Formatierungen, aber die Bezeichnungen der Klassen/die Dokumentstruktur dessen was AsciiDoc als HTML generiert und die Klassen im CSS von Nikola stimmen nicht überein - es kennt zum Beispiel keine Klasse "listinblock"
Das heißt viele Dinge die eigentlich im AcsiiDoc-Dokument was man erstellt hat formatiert sind oder eine besondere Bedeutung haben, werden unformatiert ausgegeben in der gerenderten Seite.

Lösung

Nikolas Themes erlauben das einbinden eigenes CSS in dem man es unter "/files/assets/css/custom.css" ablegt.
Das CSS von AcsiiDoc kann man mit folgendem Aufruf bekommen:

acsiidoctor -b html5 -o /tmp/outfile.html irgendeinasciidocfile.asc

Asciidoc-Files meint hier die Dateien unter posts/ die man asciidoc-Formatiert erstellt hat.

Anschließend findet man unter /tmp/outfile.html die gerenderte Datei, in dessen Header das gesamte CSS welches Acsiidoctor normalerweise einfügen würde.



 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.16">
<title>Fazit</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
html{font-family:sans-serif;-webkit-text-size-adjust:100%}
a{background:none}

Der CSS-Teil beginnt hier in Zeile 10 mit dem "<style>" → alles danach bis zum auftreten von "</style>" ist CSS.
Es kann mehrere "<style>"-Sektionen geben, wenn in AsciiDoctor Gems/Plugins aktiviert sind (wie Syntax-Highlighting).

Man kopiert alles was zwischen den <style>-Tags steht (zwischen allen, exklusive der Style-Tags) und kopiert es nach "/files/assets/css/custom.css" in seiner Nikola-Installation.

Anschließend baut man das Dokument mit:

nikola build
⚠

Das CCS in der custom.css überschreibt ggf. Werte von Nikolas eigenem CSS und verändert Teile des Blogs die nicht verändert werden sollen.
Das wird vor allem bei Regeln der Fall sein die sich auf Elemente beziehen - also Regeln die kein "#" oder "." beinhalten.

Die custom.css wird als letztes eingelesen und damit zu letzt zum zusammengeführten css-File hinzugefügt → Regeln die später kommen überschreiben frühere Regeln in css (es sei denn die vorherkommenden Regeln sind spezifischer). Ist das der Fall muss ggf. analysiert werden welche Regeln das unerwünchte Verhalten verursachen und diese angepasst/gelöscht werden.
💡

Will man spezifischere (ließ: Lassen sich Regeln nicht überschreiben) Regeln von Nikola in der custom.css überschreiben kann man "!important" in den Regeln benutzen um das zu erzwingen:

html {background-color:#FFFAF0!important}

Sonstiges

Eine custom.css die das Default-CSS aus AsciiDoctor beinhaltet und eine Version die ich benutze findet man hier: https://codeberg.org/shellkraut/AsciiDoc_nikola_css