Skip to content

Gutenberg tips and quirks for child theme developers

Jump to bottom Edit New page
Nick Cernis edited this page Oct 11, 2018 · 2 revisions

A page outlining known issues and workarounds with Gutenberg as it pertains to theme development and support.

Intended as an addendum to https://wordpress.org/gutenberg/handbook/extensibility/theme-support/.

Horizontal scroll bars with wide blocks

Adding wide blocks causes horizontal scroll bars to appear in Chrome/Firefox on Mac (with “Always” on for scroll bars in System Preferences → General):

Show scroll bars always setting.

https://github.com/studiopress/genesis-sample/issues/91.

The workaround at present is to apply overflow-x: hidden; to the body or .site-container elements. We also recommend you use word-wrap: break-word; on the .site-container element if overflow is hidden.

WordPress gallery styling

WordPress galleries added via Gutenberg use ul for the markup. As StudioPress themes have margin on our content ul, this causes the galleries to be shifted to the right instead of centered.

Fix is to:

  1. Ensure .entry-content ul uses padding for spacing.

  2. Apply zero padding left to ul gallery blocks:

.entry-content .wp-block-gallery {
    padding-left: 0;
}

Checking if a page contains blocks

In some cases we may wish to apply styling to pages with blocks differently than those without blocks, or include scripts and styles on pages with certain blocks only.

This can be achieved using the has_blocks Gutenberg function to add a body class on pages with blocks:

add_filter( 'body_class', 'sp_has_gutenberg_blocks' );
function sp_has_gutenberg_blocks( $classes ) {
	if ( has_blocks() ) {
		$classes[] = 'has-blocks';
	}

	return $classes;
}

We can also check if a page has a specific block with has_block:

add_filter( 'body_class', 'sp_has_gutenberg_paragraph_block' );
function sp_has_gutenberg_paragraph_block( $classes ) {
	if ( has_block( 'paragraph' ) ) {
		$classes[] = 'has-paragraph-block';
	}

	return $classes;
}

Where has_block( 'paragraph' ) can be replaced with the block name as it appears in the Gutenberg code editor:

Gutenberg raw editor showing blocks with WordPress comments.

Adding editor styles

Adding editor styles is supposed to follow the process outlined here:

However, there are various styles (full-width blocks) that still require additional CSS selectors to override inline styles with this method.

Alternative approaches are being explored.

For now, we are enqueuing styles directly instead of using add_theme_support( 'editor-styles' ); For example, in Genesis Sample:

add_action( 'enqueue_block_editor_assets', 'genesis_sample_block_editor_styles' );
function genesis_sample_block_editor_styles() {

	wp_enqueue_style( 'genesis-sample-block-editor-fonts', '//fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,700', array(), CHILD_THEME_VERSION);
	wp_enqueue_style( 'genesis-sample-block-editor-styles', get_theme_file_uri( '/style-editor.css' ), false, '1.0', 'all' );

}

Editor width

The documentation for defining element widths in editor styles does not currently work correctly. An issue is at https://github.com/WordPress/gutenberg/issues/9894.

A workaround at present is to use more specific editor rules to override inline styles added after the editor stylesheet. Instead of this in style-editor.css:

body.gutenberg-editor-page .editor-block-list__block …

We can use this:

body.wp-admin.gutenberg-editor-page .editor-block-list__block …

“Updating failed” message or 403 errors when editing pages with Gutenberg

Causes include:

Add a custom footer
Add a custom sidebar
Clone this wiki locally