Editor-Styles für Gutenberg erstellen

Optimalerweise bekommen Nutzerinnen und Nutzer schon im Editor einen Eindruck davon, wie der Inhalt im Frontend aussehen wird. Dafür können Editor-Styles erstellt und eingebunden werden, die den Editor optisch an das Frontend anpassen.

Dabei gibt es ein paar Dinge zu beachten, um halbwegs frustfrei ans Ziel zu kommen.

Unterscheidung zwischen Styles für Blöcke und Styles für das Editor-UI

Ich unterscheide in Projekten in der Regel zwischen Styles für die Blöcke und Styles, die das User-Interface vom Editor betreffen, also etwa die Sidebar mit Blockeinstellungen. Die UI-Styles sind leider (noch(?)) notwendig, um etwa unnötige Core-Blockeinstellungen zu verstecken, sofern sie denn über eine eindeutige Klasse verfügen.

Es gibt also beispielsweise eine editor-styles.css mit den Block-Styles und eine editor-ui-styles.css mit den UI-Styles. Die Einbindung beider Dateien unterscheidet sich in einem wichtigen und für uns hilfreichen Punkt, denn WordPress kann uns dabei behilflich sein, dass die Block-Styles nicht versehentlich auf das ganze UI wirken (was sonst möglich wäre, da wir es nicht wie bei dem alten Editor mit einem iFrame zu tun haben, sondern der Editor direkt Teil des übrigen Backend-Markups ist).

Editor-Block-Styles einbinden

Die add_editor_style()-Funktion dürfte einigen bereits aus Tagen des Classic Editors bekannt vorkommen – damit ließen sich bereits dafür Editor-Styles einbinden. Bei Gutenberg benötigen wir zusätzlich noch den Aufruf von add_theme_support( 'editor-styles' );. Der sorgt dafür, dass die Styles wirklich eingebunden werden und – wichtig – dass alle CSS-Selektoren am Anfang mit einem .editor-styles-wrapper versehen werden.

Dadurch werden auch sehr allgemeine Regeln, wie für h1 und p, nur auf den Block-Bereich des Editors angewendet, und nicht auf das restliche Interface des Backends. Aus diesem Grund ist es häufig möglich, viel CSS vom Frontend für den Editor wiederzuverwenden.

Die Einbindung kann dann wie folgt aussehen, wenn das Stylesheet im Theme unter assets/css/editor/editor-styles.css liegt:

/**
 * Enqueues theme styles for the editor.
 */
add_action( 'after_setup_theme', function() {

	// Add support for editor styles.
	add_theme_support( 'editor-styles' );

	// Enqueue block editor stylesheet.
	add_editor_style( 'assets/css/editor/editor-styles.css' );
} );Code-Sprache: PHP (php)

Ein paar Besonderheiten

CSS für html und body wird auf den .editor-styles-wrapper-Selektor umgeschrieben und muss beispielsweise im Hinblick auf die globale Schriftgröße vermutlich angepasst werden, da der Backend-body eine Schriftgröße von 13px hat, die sich auf relative Angaben für das Frontend entsprechend auswirkt. Daher dürfte die Schrift im Block-Bereich ohne Anpassung meist zu klein sein.

Die Maximalbreite der Blöcke im Backend könnt ihr über den .wp-block-Selektor festlegen. Ein leicht angepasstes Beispiel von der »Theme Support«-Seite aus dem Block-Editor-Handbuch:

/* Main column width */
.wp-block {
    max-width: 800px;
}
 
/* Width of "wide" blocks */
.wp-block[data-align="wide"] {
    max-width: 1080px;
}
 
/* Width of "full-wide" blocks */
.wp-block[data-align="full"] {
    max-width: none;
}Code-Sprache: CSS (css)

Damit ist die Standardbreite von Blöcken im Editor auf 800 Pixel gesetzt, Blöcke mit der breiten Breite werden maximal 1.080 Pixel breit und Blöcke, die über die gesamte Breite gehen sollen, haben keine Maximalbreite.

Nacharbeiten oft notwendig

Sofern es sich nicht um eine ganz einfache Site handelt, die nur Überschriften, Absätze und vielleicht hier und da noch ein Bild nutzt, ist es in der Regel notwendig, Styles aus dem Frontend mit Regeln in dem Editor-Stylesheet zu überschreiben.

Wenn ein Block-Wrapper im Frontend beispielsweise ein Flex-Container ist, kann es sein, dass der Container mit dieser Klasse im Backend gar nicht direkt mehrere Kindelemente hat, sondern erst ein paar verschachtelte div-Container kommen, bevor die Elemente auftauchen, die im Frontend die Flex-Items sind. Bei mit InnerBlocks verschachtelten Blöcken wie dem Spalten-Block ist das beispielsweise der Fall.

Editor-UI-Styles einbinden

Kommen wir zu den Styles, die beispielsweise Dinge in der Sidebar verstecken sollen. Die binden wir über wp_enqueue_style() ein, innerhalb einer Funktion, die an enqueue_block_editor_assets gehängt wird:

/**
 * Enqueues editor UI styles.
 */
add_action( 'enqueue_block_editor_assets', function() {

	// Enqueue editor UI style.
	wp_enqueue_style( 'slug-editor-ui-style', get_theme_file_uri( 'assets/css/editor/editor-ui-styles.css' ) );
}Code-Sprache: PHP (php)

Bei diesen Styles wird keine Veränderung durch WordPress vorgenommen, ihr müsst also spezifisch genug sein um nur das zu verändern, was verändert werden soll.

Fazit zu Editor-Styles

Das Einbinden der Styles ist nicht wirklich schwierig, und die Nachbearbeitung der Selektoren mit .editor-styles-wrapper durch WordPress in der Regel eine große Erleichterung.

Manchmal kann es etwas nervig sein, nach den Gutenberg-Style-Regeln zu suchen, die einen bestimmten unerwünschten Effekt hervorrufen, aber ich glaube, die Entwicklerinnen und Entwickler sind dran, das Schritt für Schritt immer weiter zu vereinfachen, wie etwa im kommenden WordPress 5.4, nachzulesen in »Markup and style-related changes«.

In dem Beitrag ist auch ein Verweis auf eine interessante Passage in der »Backwards Compatibility«-Gutenberg-Readme, die besagt, dass das vom Editor erzeugte DOM und dessen CSS-Klassen nicht als öffentliche API angesehen und verändert werden können. Ich würde sagen, es ist nicht immer möglich, in Editor-Styles komplett auf das Ansprechen von Core-CSS-Klassen oder -DOM-Konstrukten zu verzichten, daher gilt es bei Updates auch immer die Editor-Styles zu überprüfen. Es könnte sein, dass Teile von genutzten CSS-Selektoren nicht mehr existieren.

Dazu steht in dem Abschnitt aber auch, dass versucht werden soll, Änderungen am DOM und CSS-Klassen wenn möglich zu vermeiden, oder eine Dev-Note darüber zu schreiben, die dann auf dem Make-Core-Blog erscheinen wird.

Es wird also auch nach einmal gut erstellten Editor-Styles bei Updates von WordPress nicht langweilig 🙃