Paste as Preformatted Gutenberg Block: Word to WordPress

Introduction to Pasting Content as Preformatted Gutenberg Block ∞

In today’s digital content landscape, the ease and efficiency of transferring or copy-pasting text from word processors like Microsoft Word to web platforms, especially WordPress as a preformatted Gutenberg block, is crucial for content creators. This article addresses this challenge head-on, seamlessly introducing an approach to paste text as a preformatted Gutenberg block. By implementing custom markers – {{pre}} and {{/pre}} – in our WordPress child theme’s functions.php file, we ensure a smooth transition of preformatted text from Microsoft Word to Gutenberg. This solution enhances workflow efficiency and upholds the integrity of your text’s formatting.

The current article is "6.22. Paste as Preformatted Block" of our Complete SEO Guide Box.
Previous Article: 6.21. Paste Code to Gutenberg. Next Article: 6.23. Mini/Aggregation Issues

You can read more about pasting content from Microsoft Word to Gutenberg editor, including supported text formatting types and styles.

Understanding Gutenberg and Preformatted Text ∞

Overview of Gutenberg Editor

Basic Functionalities

The Gutenberg editor, named after the printing press inventor, revolutionized WordPress content creation with its block-based approach. It allows users to build and edit web pages and posts using a variety of blocks, such as paragraphs, images, and tables. This modern editor provides a more visual and intuitive user interface, making website content creation accessible to all skill levels.

Handling of Pasted Text

When pasting text into Gutenberg, users often face a common issue: the editor’s struggle to convert pasted content to specific block types they need. While Gutenberg attempts to convert the pasted content into its block types, the process is not foolproof, often requiring additional formatting adjustments by the user.

Preformatted Block in Gutenberg

Definition and Use Cases

The preformatted block in Gutenberg is a specific block type designed to display text exactly as it’s entered, preserving spaces and line breaks. This block is handy for code snippets, ASCII art, or any content where maintaining the original formatting is crucial.

Limitations with Standard Methods

Typically, inserting preformatted text into Gutenberg involves manually selecting and converting text into a preformatted block. However, this method can be time-consuming and inefficient, especially for large texts. Moreover, standard shortcodes often fall short of preserving the intricate formatting of text pasted from applications like Microsoft Word. These limitations call for a more robust solution, where our custom markers – designed to paste as preformatted Gutenberg blocks – come into play.

Explanation of the Solution: Custom Markers for Preformatted Blocks ∞

We introduce a unique solution: custom markers to address the challenge of pasting text into the Gutenberg editor and converting it to the preformatted block on publish. These markers, designated as {{pre}} and {{/pre}}, act as cues for the WordPress system to recognize and automatically convert the enclosed text into a preformatted block upon publishing. This method simplifies pasting as preformatted Gutenberg blocks, ensuring that text formatting from Microsoft Word is seamlessly preserved in the Gutenberg editor.

We already explained the problem of using shortcode markers [] and [/] in the previous article about pasting text from word processors to WordPress Gutenberg editor and converting it to code block on publish. In addition, the process of setting up the environment is already covered in this article. However, we will provide a summarized overview of the problem, method, and setup before giving the actual PHP code to paste with its detailed breakdown.

Issues with Pasting Text in Gutenberg and Why Traditional Shortcodes Are Not Ideal

Standard shortcodes often fail to preserve the formatting when pasting text from Microsoft Word into Gutenberg, leading to additional manual adjustments.

Traditional shortcodes, typically enclosed in square brackets, are not designed to handle complex formatting scenarios, especially with content pasted from external sources like Microsoft Word that use formatted text rather than unformatted like Notepad.

When shortcodes are recognized on paste into Gutenberg editor, they’re converted to shortcode blocks, adding additional HTML styling tags that aren’t part of the content, making them unusable. So, in this case, creating a custom function that utilizes [pre] and [/pre] to convert text to a preformatted block isn’t a solution.

Introduction to {{pre}} and {{/pre}} Markers

Our solution utilizes {{pre}} and {{/pre}} as custom markers. These markers are placed around the text in Microsoft Word before pasting into Gutenberg. Upon publishing, these markers trigger the conversion of the enclosed text into a preformatted block. This conversion will happen only when showing the final text to the user in the frontend but not in the post-editing. This means this function doesn’t change the source.

Advantages Over Traditional Shortcodes

Unlike standard shortcodes, our custom markers are specifically designed to handle the pasting of text from Word to Gutenberg while converting it to the preformatted block on publish. They ensure the formatting is preserved without additional manual adjustments, streamlining the content creation process.

Importance of Using a Child Theme for Modifications

Modifying WordPress themes directly can be risky, as updates to the theme can overwrite custom changes. To avoid this, we use a child theme. This separate theme inherits the functionality of the parent theme but allows for safe customization. By using a child theme, modifications like our custom markers remain intact, even after theme updates, ensuring a stable and update-proof WordPress environment.

Preparing the WordPress Environment, Setting Up a Child Theme

A child theme in WordPress is a sub-theme that inherits the style and functionality of another theme, referred to as the parent theme. Child themes are the safest and most efficient way to modify an existing theme because they allow you to apply custom changes without affecting the parent theme. Check out our comprehensive guide on how to create and activate a WordPress child theme.

Understanding of functions.php in our Solution

The functions.php file in a WordPress theme acts as a plugin, allowing you to add features and customize your theme without altering the core WordPress files.

In this solution, functions.php plays a crucial role as it will house the custom PHP function that interprets our custom markers ({{pre}} and {{/pre}}) and converts the marked text into preformatted blocks when the content is published.

Accessing functions.php

On the left side menu bar, hover over [Appearance], then click on [Theme File Editor] in the pop-up menu.
On the right menu, click on “functions.php”.
Paste our PHP code at the end of the file.
Click [Update File].
Clear all the caches.

The Custom PHP Function to Convert Pasted Text to Preformatted Gutenberg Block ∞

This code snippet added to the functions.php file of a WordPress child theme is designed to convert text between specific markers {{pre}} and {{/pre}} within post content into a preformatted block in the WordPress Gutenberg editor. The conversion will be only for the frontend for the users to see and not for the original content in the post edit.

function convert_to_preformattedblock($content) {
    // Handling {{pre}}...{{/pre}} for preformatted blocks
    $pattern_preformatted = '/\{\{pre\}\}\n?(.*?)\{\{\/pre\}\}/s';
    $replacement_preformatted = '<pre class="wp-block-preformatted">$1</pre>';
    return preg_replace($pattern_preformatted, $replacement_preformatted, $content);
}

// Add the filter to the_content
add_filter('the_content', 'convert_to_preformattedblock', 9);

The next is the same function only to shorter the ‘pre’ usage to only ‘p’:

function convert_to_preformattedblock($content) {
    // Handling {{}} and {{/}} markers with 'p' inside for preformatted blocks
    $pattern_preformatted = '/\{\{p\}\}\n?(.*?)\{\{\/p\}\}/s';
    $replacement_preformatted = '<pre class="wp-block-preformatted">$1</pre>';
    return preg_replace($pattern_preformatted, $replacement_preformatted, $content);
}

// Add the filter to the_content
add_filter('the_content', 'convert_to_preformattedblock', 9);

Detailed Breakdown of the PHP Function ∞

Let’s break down each part of the code for a clearer understanding:

Function Definition

function convert_to_preformattedblock($content) {

• This line defines a new function in PHP named convert_to_preformattedblock. The function takes one parameter, $content, representing the post or page being processed.

Handling Custom Markers

// Handling {{pre}}...{{/pre}} for preformatted blocks
$pattern_preformatted = '/\{\{pre\}\}\n?(.*?)\{\{\/pre\}\}/s';
$replacement_preformatted = '<pre class="wp-block-preformatted">$1</pre>';
return preg_replace($pattern_preformatted, $replacement_preformatted, $content);

• // Handling {{pre}}...{{/pre}} for preformatted blocks: This is a comment for clarity, explaining that the following lines of code are for handling text enclosed within {{pre}} and {{/pre}} markers.
• $pattern_preformatted = '/\{\{pre\}\}\n?(.*?)\{\{\/pre\}\}/s';: This line defines a regular expression pattern to match the custom markers.
  • /\{\{pre\}\}\n?(.*?)\{\{\/pre\}\}/s: The regular expression looks for text that starts with {{pre}} and ends with {{/pre}}. The s modifier at the end of the pattern allows the dot . in the pattern to match newline characters, so the text between the markers can span multiple lines.
  • \n?: This optionally matches a newline character after {{pre}}, so the pattern works whether or not there's a newline right after the opening marker.
• $replacement_preformatted = '<pre class="wp-block-preformatted">$1</pre>';: This line defines the replacement HTML. The $1 back-reference includes the text between the custom markers.
  • <pre class="wp-block-preformatted">: The <pre> tag is used for preformatted text in HTML, and wp-block-preformatted is a CSS class that likely styles the preformatted block in a way consistent with Gutenberg's style.
• return preg_replace($pattern_preformatted, $replacement_preformatted, $content);: This line performs the actual replacement. The preg_replace function searches $content for matches to $pattern_preformatted and replaces them with $replacement_preformatted. The modified content is then returned.

Adding the Function to WordPress Content Filter

// Add the filter to the_contentadd_filter('the_content', 'convert_to_preformattedblock', 9);

• add_filter('the_content', 'convert_to_preformattedblock', 9);: This line hooks the convert_to_preformattedblock function to the the_content filter in WordPress, which is applied to the content of posts and pages before they are output to the screen.
  • 'the_content': This is the name of the filter hook.
  • 'convert_to_preformattedblock': This is the name of the function to be hooked.
  • 9: This is the priority of the function. The default priority of functions in 'add_filter' is 10. We set it to 9 to ensure this function is executed before WordPress's default formatting functions.

Ensuring Accurate Text Conversion: Setting Priority in Function Hooks ∞

When we set the priority of our custom function to '9' in the WordPress filter hook, we do so to address a common challenge in content formatting within WordPress and the Gutenberg editor. WordPress, many WordPress themes, and Gutenberg itself include internal functions that automatically alter text in various ways.

A typical example of such alteration is the conversion of regular double quotes into smart (curly) double quotes. While this feature enhances the readability of standard text, it can be problematic in preformatted blocks where the exact representation of the original text, including special characters, is essential.

By assigning a priority of '9' to our convert_to_preformattedblock function, we ensure that it executes just before the default WordPress formatting functions, which typically run at a priority of '10'. This earlier execution effectively circumvents any automatic character conversions or alterations that WordPress might apply.

As a result, the text enclosed within our custom {{pre}} and {{/pre}} markers is preserved strictly as intended when being converted to a preformatted block in the Gutenberg editor. This precision is especially beneficial for those looking to paste as preformatted Gutenberg blocks, where maintaining the integrity of the original text, including special characters, is paramount.

If you still experience issues with text formatting and styling inside the preformatted block after publishing, try changing the priority to a higher number, like '8', clearing all the caches, and checking again.

Converting to Preformatted Blocks on Practice ∞

How the Markers Work Upon Publish

The custom markers {{pre}} and {{/pre}} play a pivotal role in the process of converting text into preformatted blocks within the Gutenberg editor, especially when dealing with content pasted from Microsoft Word. Here's an overview of how these markers function upon publishing your WordPress content:

1. Detection of Markers: When you publish or update a post or page, WordPress processes the content. During this stage, the code in your functions.php file scans the content for our custom markers.
2. Activation of the Function: Upon finding text enclosed within {{pre}} and {{/pre}}, the function convert_to_preformattedblock is triggered. This function is designed to recognize these markers. It is set to execute before WordPress applies its default formatting rules, thanks to its priority setting of '9'.
3. Conversion to Preformatted Block: The function replaces the markers and the text between them with a <pre> HTML tag, effectively converting it into a preformatted block. The wp-block-preformatted class applied in this process ensures that the block adheres to the styling conventions of Gutenberg blocks.
4. Preservation of Original Formatting: This conversion process is crucial for maintaining the text's original formatting, precisely as in the Microsoft Word document. This is particularly important for content where the precise layout and spacing are essential, a common requirement when you paste as a preformatted Gutenberg block.

Visual Representation of the Conversion

The visual change from plain text within custom markers to a preformatted block is quite noticeable:

• Before Conversion: Initially, the text appears in the editor with the {{pre}} and {{/pre}} markers visible at the beginning and end of the block of text.
• After Conversion: Once published, these markers are no longer visible. Instead, the text is displayed in a distinct box, typically with a monospaced font and a background color that differentiates it from the rest of the content. This indicates that the text is now in a preformatted block, preserving the original formatting from the Word document.

Testing the Implementation ∞

Once you have implemented the custom function in your functions.php file, testing it to ensure it operates as expected is essential. The goal is to confirm that text marked with our custom {{pre}} and {{/pre}} markers is accurately converted into a preformatted block when viewed on the website. Here's a step-by-step guide to test this feature:

1. Create a Test Post: In your WordPress dashboard, create a new post.
2. Paste Sample Text: Paste a block of text from Microsoft Word into the Gutenberg editor. Surround this text with the custom markers {{pre}} and {{/pre}} before pasting.
3. Publish the Post: After adding the text, publish the post.
4. Verify the Output: View the published post. The text within the custom markers should now be displayed as a preformatted block. Ensure the formatting is retained precisely in the original Microsoft Word document.

Debugging Common Issues ∞

Even with careful implementation, you might encounter some issues. Here are common problems and how to troubleshoot them:

1. Text Not Converting: If the text doesn't convert to a preformatted block, check the syntax of the custom markers in the text. Ensure they match precisely what the functions.php code is set to recognize.
2. Formatting Issues: If the formatting doesn't match the original, inspect the CSS associated with the wp-block-preformatted class. Adjust the CSS in your child theme to match your desired formatting.
3. Code Not Executing: If the function doesn't seem to be executing, ensure you correctly added the function to the functions.php file in your child theme, not the parent theme.
4. Conflicts with Other Plugins or Themes: Other plugins or theme features occasionally conflict with your custom code. Deactivate other plugins one by one to identify any conflicts, and check your theme's documentation for any known issues.

Pasting Text from Microsoft Word ∞

Tips for Formatting in Word

Before you paste your text into the Gutenberg editor, preparing it correctly in Microsoft Word is essential. This preparation is crucial for ensuring the text maintains its integrity when utilizing the 'paste as preformatted Gutenberg block' feature. Here are some tips for formatting your text in Word:

1. Keep Formatting Simple: While Word offers many formatting options, remember that complex formatting may not always translate perfectly into Gutenberg. Stick to basic formatting elements like bold, italics, and bullet points.
2. Use Standard Fonts: Stick to common, web-safe fonts to ensure consistency when the text is pasted into Gutenberg. Unusual or custom fonts might not be supported and can lead to formatting discrepancies.
3. Avoid Text Boxes and Columns: These elements often do not translate well into web formats. Instead, format your document in a linear, straightforward manner.
4. Prepare for Preformatted Style: Since converting text into a preformatted block, ensure it looks exactly how you want it to appear on your website. This includes paying attention to line breaks, spacing, and indentation.

Pasting into Gutenberg and Adding Markers

Once your text is prepared in Word, the next step is to paste it into the Gutenberg editor and apply the custom markers for conversion into a preformatted block.

1. Add Custom Markers: Before and after the text you want to appear as a preformatted block, manually insert the custom markers {{pre}} and {{/pre}}. Make sure there are no extra spaces or characters that could interfere with the markers being recognized correctly.
2. Adjust as Needed: After adding the markers, you may need to make minor adjustments to the text to ensure it's formatted as you need.
3. Copy from Word: Highlight the text in your Word document and copy it to your clipboard.
4. Paste into Gutenberg: In your WordPress dashboard, create a new post or page. After that, paste the copied text into the Gutenberg editor.
5. Preview the Post: Before publishing, preview the post to verify that the text within the custom markers appears as a preformatted block. This step is crucial to ensure that the 'paste as preformatted Gutenberg block' process has been successful.

Conclusion ∞

Mastering the process of pasting content as preformatted Gutenberg blocks is an invaluable skill for any WordPress user who frequently works with text imported from Microsoft Word. By strategically implementing custom markers in the functions.php file of a child theme, users can overcome the challenges of preserving original text formatting in the Gutenberg editor. This method not only streamlines the workflow but also ensures that the textual integrity and formatting of the original document are maintained.

As we have explored, carefully setting up the environment, crafting the custom markers, and testing and troubleshooting are critical to successfully integrating this functionality. Users can effectively navigate common pitfalls and optimize their WordPress content creation process by following the guidelines and techniques discussed.

This approach demonstrates a significant advancement in managing content formatting, addressing a specific need in the WordPress community. Whether you are a blogger, a developer, or a content manager, understanding how to paste content as preformatted Gutenberg blocks will enhance the efficiency of your website management.

The current article is "6.22. Paste as Preformatted Block" of our Complete SEO Guide Box.
Previous Article: 6.21. Paste Code to Gutenberg. Next Article: 6.23. Mini/Aggregation Issues

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