Home » Themes & functions.php » WordPress Code Block Visual CSS Customization – Child Theme

WordPress Code Block Visual CSS Customization – Child Theme



In the ever-evolving landscape of web development, how content is presented (like WordPress code block) can significantly affect user engagement and readability. WordPress is a platform that consistently adapts to the needs of its vast user base. A key element in WordPress’s arsenal is the Gutenberg editor, which has revolutionized content editing. However, even with its advanced features, customizing the visual appearance of some aspects, like the code block, can be challenging. This post dives into the nuances of enhancing the visual and functional elements of the WordPress code block, specifically through CSS customization in a Child Theme.

The current article is "6.20. Code Block Customization" of our Complete SEO Guide Box.
Previous Article: 6.19. Multi-part Post by Menu Items. Next Article: 6.21. Paste Code to Gutenberg

Brief Overview of WordPress Gutenberg Blocks

WordPress revolutionized content management with the introduction of the Gutenberg editor. This block-based editor allows users to build and design their content with various blocks, each serving a unique purpose – from paragraphs and images to more complex elements like tables and, notably, code blocks. Gutenberg’s intuitive interface simplifies the content creation, offering a more visual approach than the classic editor. However, when it comes to specific customization needs, especially for code blocks, the default settings might not suffice, highlighting the need for a more tailored approach.

Importance of Customizing Code Blocks for Readability and Aesthetics

The readability and aesthetics of code blocks are paramount for any website with coding tutorials, developer blogs, or technical documentation. A well-presented code block enhances readability and elevates the overall user experience. Default code blocks in WordPress often come with basic styling, which may not align with your site’s theme or the expectations of your audience. Customizing these blocks, particularly for readability and aesthetic appeal, becomes not just a preference but a necessity. It ensures your content is digestible and visually engaging, encouraging users to interact more with your material.

Overview of the Approach: Using CSS in a Child Theme

Currently, CSS in a Child Theme is the most effective and sustainable way to customize the WordPress code block. This approach offers several advantages. Firstly, using a Child Theme ensures your customizations are preserved after the parent theme is updated. Secondly, by utilizing CSS, you gain granular control over the styling of your code blocks (font size, color scheme, layout, responsiveness, and more). We will guide you through setting up a Child Theme and using CSS to transform the appearance and functionality of your WordPress code blocks, ensuring they stand out and effectively convey your coded message.

The Problem with Default Code Block Appearance

When diving into WordPress blogging or website development, one quickly encounters the default WordPress code block appearance limitations. While robust in many aspects, the core Gutenberg editor often fails to provide an optimal display for code snippets. This shortcoming becomes evident when dealing with complex or lengthy code, where the default settings do not always cater to the needs of developers or readers interested in technical content.

Issues with Wrapping and Readability

One of the primary issues with the default WordPress code block is how it handles text wrapping. In many instances, code lines extend beyond the viewable area of the block, leading to wrapped lines that can disrupt the code’s structure and flow. This wrapping makes the code harder to read. It increases the likelihood of errors or misunderstandings, especially for those trying to follow along or learn from the code. The absence of a horizontal scrollbar means that users cannot easily view long lines of code in their entirety, which can be particularly problematic for languages where line length is crucial. Addressing this issue is essential to enhance the usability and readability of the WordPress code block.

Lack of Aesthetic Appeal

Another significant drawback of the default WordPress code block is its lack of aesthetic appeal. The standard styling – often a plain background with minimal formatting – does little to make the code stand out from the rest of the content. This lack of visual differentiation can lead to a monotonous and unengaging user experience for websites that frequently feature code snippets. Therefore, Customizing the code block’s appearance is about functionality and creating a visually appealing and engaging environment. A well-designed code block, with a thoughtful color scheme and typography, can significantly enhance a website’s overall look and feel, making technical content more accessible and appealing to a broader audience.

Understanding the Limitations of WordPress Code Highlight Plugins

While WordPress code highlight plugins offer a seemingly easy solution for enhancing the appearance of code blocks, they come with limitations. These limitations can impact the functionality and long-term viability of using such plugins for customizing the appearance of the WordPress code block in your website. Developers and content creators must understand these constraints to make informed decisions about how to display code on their WordPress sites.

Common Issues with Code Highlight Plugins

The world of WordPress plugins is vast, but there are some complexities regarding code highlighting since it is not as popular. Users frequently encounter several common issues that can hinder the effectiveness of these plugins.

Not Always Working as Intended Out of the Box

A significant concern with many WordPress code-highlighting plugins is that they often do not work as intended right out of the box. Users may find that these plugins require complex configurations and tweaking instead of a simple plug-and-play solution to function correctly. The necessity to dive into detailed settings or even code adjustments defeats the purpose of using a convenient plugin, adding to the time and effort to set up the WordPress code block.

Impact on Website Performance Due to Heavy Files

Another notable issue with some code highlight plugins is their impact on website performance. These plugins often load heavy JavaScript and CSS files to display highlighted code syntax based on the language. This additional load can significantly slow down your website speed performance, affecting user experience and potentially harming your search engine ranking. This trade-off can be a dealbreaker for websites prioritizing speed and efficiency, pushing them to seek lighter, more performance-friendly methods of highlighting code.

Incompatibility and Malfunction

One of the most pressing issues with WordPress code highlight plugins is incompatibility and malfunction. As WordPress continues to evolve, with regular updates to its core and Gutenberg editor, some plugins fail to keep pace. This incompatibility can lead to plugins malfunctioning, manifesting as broken styling, incorrect code formatting, or complete failure to display the code block as intended. Such issues not only detract from the visual appeal of a website but also undermine the integrity of the code being shown, potentially leading to confusion or misinterpretation by the audience.

Quick Abandonment by Authors

Another significant problem plaguing many WordPress code highlight plugins is the quick abandonment by their authors. Plugin development and maintenance require consistent effort, often challenging for independent developers or small teams. As a result, many code highlight plugins are not regularly updated, leaving them vulnerable to security risks, incompatibility issues, and eventual obsolescence. This abandonment can be particularly troublesome for websites that rely heavily on such plugins for displaying code blocks, as it forces site owners to frequently switch plugins or find alternative solutions to keep their code presentations up to standard.

Why Opt for CSS Customization

In enhancing the WordPress code block, turning to CSS for customization emerges as a highly effective strategy. This approach stands out for several reasons, particularly when compared to plugins, which, as previously discussed, can be fraught with issues ranging from performance impacts to long-term maintenance concerns.

Reliability and Control

CSS customization offers reliability and control that is often unattainable with standard plugins. By directly modifying the style of the WordPress code block through CSS, you gain precise control over every aspect of its appearance, from the font type and size to the color scheme and layout. This direct approach eliminates the dependency on third-party plugins, which may suffer from compatibility issues or become outdated. Furthermore, CSS-based changes are typically more lightweight, avoiding the overhead of loading additional scripts or styles that can slow down your website. This ensures the customized code blocks are visually appealing and contribute positively to the site’s overall performance and user experience.

Minimal Impact on Website Speed

Another benefit of CSS customization for the WordPress code block is its minimal impact on website speed. Unlike plugins that often require the loading of extensive JavaScript libraries or large CSS files, the specific CSS customizations we suggest are much smaller in size. This lean approach means that the additional styling for the code blocks adds negligible weight to your website’s overall load time. You can achieve the desired styling effects by implementing concise and optimized CSS code without burdening your site’s performance. This aspect is crucial for maintaining a fast page load, enhancing user experience, and improving SEO rankings.

Simplicity and Ease of Use

One of the most compelling advantages of using CSS for customizing WordPress code blocks is its simplicity and ease of implementation. Even those with basic knowledge of CSS can significantly improve the aesthetics and functionality of their code blocks. Unlike plugin configurations that can be complex and unintuitive, CSS allows for straightforward, readable, and easy-to-update customizations. This simplicity also makes troubleshooting and adjustments more manageable, as you’re dealing with clear, concise code rather than navigating through a plugin’s interface or dealing with potential conflicts among multiple plugins.

Long-term Solution

Opting for CSS customization is also a strategic decision regarding long-term viability. Unlike plugins, which may be abandoned by their developers or become incompatible with future WordPress updates, CSS customizations in a Child Theme are generally more sustainable. As you maintain control over the styling, updating, or tweaking, the appearance of the WordPress code block to align with new requirements or design trends becomes more manageable. This approach future-proofs your customizations, ensuring that your code blocks will continue to look and function as intended, even as the underlying WordPress platform evolves. Investing in CSS customization establishes a stable and adaptable foundation for presenting code on your website, making it a prudent choice for anyone committed to delivering high-quality, technically-oriented content over the long term.

Acknowledging the Limitation: Lack of Syntax Highlighting

While our CSS customization approach for WordPress code blocks offers numerous advantages, it’s essential to acknowledge a notable limitation: the lack of automatic syntax highlighting. Syntax highlighting – the feature that differentiates functions, variables, and other elements through color coding – is common in many code highlight plugins but is not inherently available through basic CSS customizations.

While CSS can significantly improve a code block’s visual appeal and readability by changing background colors, fonts, and layouts, it does not parse the code to apply distinct styling to different syntax elements. This could be a significant drawback for users requiring detailed syntax highlighting. However, CSS customization remains an effective and efficient solution for those primarily seeking to enhance their code blocks’ overall readability and aesthetics.

The Basics of WordPress Child Themes and Setting Up

In the journey of customizing WordPress code blocks, understanding the concept and application of WordPress Child Themes is fundamental. A Child Theme in WordPress is a theme that inherits the functionality, features, and style of another theme, the parent theme. Child themes are used to modify/add functionality without altering the original theme files. This is important for maintaining customizations even when the parent theme is updated.

Using a Child Theme makes modifications, such as those to enhance your WordPress code block, well preserved and not overwritten during updates. It offers a safe and efficient way to apply custom changes like CSS modifications, ensuring both the longevity and flexibility of your website’s design and functionality.

Setting Up a Child Theme

Follow our comprehensive guide on creating and setting up a WordPress child theme.

Customizing the Gutenberg Code Block: A CSS Approach

Taking control of the appearance and functionality of the WordPress code block within the Gutenberg editor can be efficiently achieved through CSS customization. This approach allows for precise and tailored styling, enhancing the overall look and readability of code blocks on your website.

Accessing and Editing the Style.css File

Once your Child Theme is set up, the next step in customizing the WordPress code block is to locate and edit the “style.css” file within this theme. This file is the cornerstone of your CSS customizations and is where all your style rules for the code block will be added.

Login to your WordPress dashboard.
On the left side menu, hover over [Appearance], then click [Theme File Editor].
On the right menu, click on the “style.css” file to edit.

CSS Code to Paste in style.css

Here is our simple solution for a scrollable black background white font code block:

/* Code block customization */
.wp-block-code {
    overflow-x: auto; /* Enables horizontal scrolling */
    background-color: black; /* Changes background color to black */
    color: white; /* Changes font color to white */

.wp-block-code code {
    white-space: pre; /* Keeps code formatting intact */

After you paste the code, click [Update File].
Clear all the caches.
Test your changes by navigating to the page with a code block.

Detailed Breakdown

  1. /* Code block customization */:
    • This line is a comment, not actual CSS code. In CSS, comments start with /* and end with */. They are used to describe what the following code does or to leave notes for anyone reading the code. In this case, it indicates that the upcoming CSS rules are meant for “Code block customization.”
  2. .wp-block-code {:
    • This is a CSS selector that targets elements with the class wp-block-code. In WordPress, this class is added by the Gutenberg editor to code block elements. The CSS rules enclosed within the curly braces {} will apply to all elements with this class.
  3. overflow-x: auto;:
    • This CSS property controls the horizontal overflow of the content within the code block element. Setting it to auto enables a horizontal scrollbar to appear if the content (code) is wider than the block’s width. This prevents code from wrapping onto the following line and keeps it on a single horizontal line, improving readability.
  4. background-color: black;:
    • The property changes to black the background color of the code block. A darker background is often preferred in code blocks as it makes the text, especially syntax highlighting, more legible and less straining to the eyes.
  5. color: white;:
    • This sets the font color of the text inside the code block to white. The high contrast of white text on a black background is effective for readability, especially for code.
  6. }:
    • This marks the end of the .wp-block-code selector’s rules.
  7. .wp-block-code code {:
    • This selector targets <code> elements within the .wp-block-code elements. It is a more specific selector, meaning it will only apply to <code> tags nested inside elements with the wp-block-code class.
  8. white-space: pre;:
    • The white-space property controls how the white space inside the element is handled. Setting it to pre preserves white spaces and line breaks as they are in the code. This is crucial for maintaining the original formatting of the code, ensuring that it is displayed exactly as it was written.
  9. }:
    • This closes the .wp-block-code code selector.

This CSS code customizes WordPress code blocks by adding a horizontal scrollbar for wider code lines, changing the background to black and the text color to white for better contrast and readability, and ensuring that the original formatting of the code is preserved.

Optional Styling Options

Beyond changing the background and font color, you can further customize the appearance of your code blocks by adjusting the font family, size, and other properties. For example:

font-family: 'Courier New', monospace; /* Sets a specific font for the code block */
font-size: 16px; /* Adjusts the size of the text */
line-height: 1.5; /* Adjusts the spacing between lines of text */
border-radius: 5px; /* Adds rounded corners to the code block */
padding: 10px; /* Adds space around the text inside the code block */

Ensuring Responsiveness and Cross-Browser Compatibility

To provide an optimal user experience, your WordPress code block customizations must be responsive and compatible across various browsers. This ensures your website’s code blocks are functional, regardless of device or browser choice.

Testing Across Browsers and Ensuring Consistent Appearance

Cross-browser compatibility ensures your website’s features and design appear consistently across browsers. Since browsers can render CSS differently, testing your WordPress code block customizations in multiple browsers (like Chrome, Firefox, Safari, and Edge) is important to ensure they look and function as intended.

  1. Testing Process: Use different browsers to view your WordPress site and check the appearance and functionality of the code blocks. Look for discrepancies in layout, color, font, and interactivity (like scrolling).
  2. Fixing Inconsistencies: If you notice any issues, you may need to adjust your CSS. This could involve using browser-specific CSS prefixes or tweaking your styles to achieve a more uniform appearance.

For example, if a certain style isn’t appearing correctly in Safari, you might need to use a WebKit-specific property:

.wp-block-code code {
    -webkit-font-smoothing: antialiased; /* Improves text rendering in Safari */

Maintaining and Updating Your Custom CSS

Effective maintenance and regular updates are crucial to ensuring that your custom CSS for WordPress code blocks continues to function correctly and remains visually appealing. This is especially important in the dynamic environment of WordPress, where updates to the Gutenberg editor can affect how your customizations work and look.

Keeping Up with Gutenberg Updates and Monitoring Changes in Block Structure

Staying informed about updates to the Gutenberg editor is crucial. These updates can sometimes alter the HTML structure or classes used for blocks, including the WordPress code block. Changes in structure can directly impact how your CSS customizations apply to these blocks.

Adjusting CSS Accordingly

When updates occur, it’s essential to:

  1. Review the Release Notes: WordPress release notes often mention changes to the Gutenberg editor. Review these notes for any modifications that might affect code blocks.
  2. Test Your Site: After a Gutenberg update, check your code blocks to see if your customizations are still working as intended. Pay attention to layout, formatting, and responsiveness.
  3. Update Your CSS: If an update has altered how your CSS affects the code blocks, you must adjust your CSS to accommodate these changes. This might involve changing selectors, tweaking properties, or adding new rules.

CSS Customizations Work on Publishing and not in Preview

When in your post or page editing mode, you can navigate to the right corner and near the [Publish]/[Update] button, click the “Preview” button, then in the pop-up menu, click [Preview in new tab].

The preview option doesn’t always show the changes made in the style.css file of your WordPress Child theme. When you publish the post, they do show to the end user.


Customizing WordPress code blocks through CSS in the Gutenberg editor is more than just an aesthetic enhancement; it’s a crucial step in improving your website’s readability and user engagement. As we’ve explored, the default settings of Gutenberg code blocks may not always align with your site’s design or the specific needs of your content. By implementing CSS customizations, you gain control over the appearance and functionality of these blocks, ensuring they are visually appealing and provide a seamless experience for your users.

Explore and Experiment with CSS

The journey of customizing WordPress code blocks is an opportunity to dive into the creative and technical aspects of web design. Whether you are a seasoned developer or a beginner, experimenting with CSS offers a platform for continuous learning and innovation. The flexibility and power of CSS allow you to tailor the code blocks to fit your site’s unique style and personality. You can explore more of the possibilities that CSS customization presents. Test new styles, adapt them to different layouts, and watch how these changes enhance the overall quality of your WordPress site. Remember, each line of CSS is a step towards making your website more engaging, accessible, and professional.

The current article is "6.20. Code Block Customization" of our Complete SEO Guide Box.
Previous Article: 6.19. Multi-part Post by Menu Items. Next Article: 6.21. Paste Code to Gutenberg


If you find any mistakes or have ideas for improvement, please follow the email on the Contact page.

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.