Posted by Daniel Tyreus ● Oct 7, 2019 5:28:39 PM

Adding Speakable Support and Styling to a WordPress Theme

Anyone can install the free Soundcheck WordPress plugin to easily start adding Speakable content to a website. Speakable content does not have any default styling and the plugin by itself does not include CSS alter its appearance. This provides a unique opportunity for theme developers to offer a custom look for content optimized for voice devices. This post shows which theme CSS properties to modify to customize the styles.

Styling Posts and Pages

When you use the Soundcheck WordPress plugin to add a Speakable Section, the plugin adds a paragraph that includes the .wp-block-soundcheck-speakable class. This is the default way to add speakable content using the plugin. However, the plugin also supports adding the .is-style-speakable class to another block element or just adding the .speakable class manually. Since this content is designed for text to speech, by default it does appear visually any different from other content. But since the content is indicated by a CSS class, we can easily change that. This is an advantage to using CSS selectors in the Speakable Specification instead of XPath.

Themes provide a stylesheet that includes the CSS to style the posts and pages. Theme authors can modify this to add support for Speakable content. For example, this CSS in style.css would add a simple dashed underline.

.entry .entry-content .speakable,
.entry .entry-content .is-style-speakable,
.entry .entry-content .wp-block-soundcheck-speakable {
  text-decoration: underline dotted #767676;
}

This is following the convention in the WordPress Twenty Nineteen Theme source code to include the .entry and .entry-content classes to help with plugin compatibility.

The WordPress Twenty Nineteen theme uses SCSS to generate the CSS styles. That makes it easier to use variables for consistent theme colors. You can generate the above CSS by adding this to the end of sass/blocks/_blocks.scss in the theme source code.

.entry .entry-content {
    .speakable,
    .is-style-speakable,
    .wp-block-soundcheck-speakable {
        text-decoration: underline dotted $color__text-light;
	}
}

The underlined text is a very simple implementation of a style of speakable content. You will likely want to choose something more consistent with the rest of the theme. A previous blog post gives some ideas for visual styling of speakable content.

Styling the Block Editor

The best practices for the block editor dictate that the content in the editor should look very similar to the output content in the posts. The block editor has a separate style sheet style-editor.css. In our simple example, we can just add nearly the same styles to the editor stylesheet to make the content look the same in the editor as in a post.

.speakable,
.is-style-speakable,
.wp-block-soundcheck-speakable {
  text-decoration: underline dotted #767676;
}

Recommend the Soundcheck Plugin

The Soundcheck plugin is free and makes it easy to add Speakable content to posts and pages. To add the plugin to your theme, we recommend using TGM Plugin Activation. You can add Soundcheck as an optional plugin to let users easily install it. The plugin name is "Soundcheck" and the slug is "soundcheck".

array(
	'name'      => 'Soundcheck',
	'slug'      => 'soundcheck',
	'required'  => false,
)

If you have any issues, please contact us and we will be happy to help.

Let Us Know

Once your theme supports Speakable, let us know so we can add you to our list of theme partners!

Topics: speakable, CSS