When writing technical blog posts, displaying code blocks correctly is essential. Recently, I found the process of handling code blocks in the WordPress Gutenberg editor inefficient and started looking for a better approach. After repeated experimentation, I eventually worked out a complete workflow that moves from manual handling to automation. It resolves parsing errors while significantly improving efficiency. I am sharing the process and solution here in case you are dealing with the same code block issues. Previous approach: A Practical Record of Fixing Unstable Parsing of Multiple Shortcodes in WordPress Gutenberg
1. Current Approach: An Inefficient but Workable “Manual Three-Step Method”
At the moment, I handle code blocks as follows:
1. Step 1: Paste
[go][/go] shortcode
In the visual editor, first paste
[go]你的代码块内容[/go]. The editor automatically converts it into a predefined shortcode block (such as a <!-- wp:shortcode --> block).
2. Step 2: Manually delete the shortcode block (Figure 1) and replace it with a SyntaxHighlighter block
Find the <!-- wp:shortcode --> block that was just converted, delete it manually, and replace it with the following (Figure 2):
<code>
<!-- wp:syntaxhighlighter/code {"language":"go"} -->
<pre class="wp-block-syntaxhighlighter-code">你的代码块内容</pre>
<!-- /wp:syntaxhighlighter/code -->
</code>3. Step 3: Adjust the language attribute
If syntax highlighting is required instead of the default Plain Text, you also need to manually add an attribute such as {"language":"go"}.
Problem: This is extremely inefficient, especially when an article contains multiple code blocks.
If an article contains more than 10 code blocks, repeating the three steps above takes a lot of time and is prone to mistakes. I needed a more efficient approach.
2. Exploration and Frustration: Pasting Code Directly Causes Errors
To improve efficiency, I tried using the <!-- wp:syntaxhighlighter/code --> block shown in the code editor as a reference (Figure 3). For example:
<!-- wp:syntaxhighlighter/code {"language":"go"} -->
<pre class="wp-block-syntaxhighlighter-code">
// Walk 中序遍历树 t
func Walk(t *tree.Tree, ch chan int) {
ch <- t.Value // 这里包含 < 符号！
}
</pre>
<!-- /wp:syntaxhighlighter/code -->
However, when the code contains unescaped `<` or `>` characters (such as the `<` in `ch <- t.Value`), the editor reports an error:
The block contains unexpected or invalid content (Figure 4)
Reason: WordPress misinterprets `<` or `>` as HTML tags, causing parsing to fail.
3. Core Solution: An Automated Escaping Workflow
After several rounds of testing, I found an automated approach that requires no manual escaping and solves both the parsing-error and efficiency problems. The core idea is to use a text editor (EditPlus) to batch-replace special characters in the code while keeping the block comment syntax unchanged.
4. Detailed Steps (Completed Entirely in the Text Editor)
1. Step 1: Write the Original Content in the Text Editor
Use custom markers such as text and go to separate code blocks while preserving the original code formatting:
我正在学习 Go 语言的并发编程。
[text]
# 检查ufw是否在运行
root@wireguard-2026-0509:~# ufw status
Status: inactive
[/text]
[go]
// Walk 中序遍历树 t
func Walk(t *tree.Tree, ch chan int) {
ch <- t.Value // 这里包含 < 符号！
}
[/go]2. Step 2: Batch-Replace the Markers with Code Block Templates
Replace `[text]</code>` with:</p> <!-- /wp:paragraph --> <!-- wp:shortcode --> <!-- wp:syntaxhighlighter/code --> <pre class="wp-block-syntaxhighlighter-code"> <!-- /wp:shortcode --> <!-- wp:paragraph --> <p>Replace `<code>[/text]` with:</pre>
<!-- /wp:syntaxhighlighter/code -->
Replace `[go]</code>` with:</p> <!-- /wp:paragraph --> <!-- wp:shortcode --> <!-- wp:syntaxhighlighter/code {"language":"go"} --> <pre class="wp-block-syntaxhighlighter-code"> <!-- /wp:shortcode --> <!-- wp:paragraph --> <p>Replace `<code>[/go]` with:</pre>
<!-- /wp:syntaxhighlighter/code -->3. Step 3: Precisely Escape Special Characters in the Code Content (Figure 5)
– Key point: Select only
<pre>the code content inside the tag (excluding block comments), and perform the following replacements:
<!-- wp:syntaxhighlighter/code {"language":"go"} -->
<pre class="wp-block-syntaxhighlighter-code">
func Walk(t *tree.Tree, ch chan int) {
ch <- t.Value // 报错！
}
</pre>
<!-- /wp:syntaxhighlighter/code -->
After replacement (displayed correctly) (Figure 6):
<!-- wp:syntaxhighlighter/code {"language":"go"} -->
<pre class="wp-block-syntaxhighlighter-code">
func Walk(t *tree.Tree, ch chan int) {
ch <- t.Value // 转义后正确解析
}
</pre>
<!-- /wp:syntaxhighlighter/code -->
6. Important Notes
1. Escape only the code content, not the block comments! (In other words, do not escape
<!-- wp:... -->any characters inside the tag.)
2. The front end displays correctly: Although the code contains <, the browser automatically renders it as < after publishing, so readers see the correct code.
3. Efficiency improvement: Compared with manually adjusting each code block (5–10 minutes per 10 blocks), this approach takes only about 30 seconds per 10 blocks.
7. Summary and Recommendations
1. Moving from manual work to automation: Batch replacement in a text editor eliminates the parsing errors while greatly improving processing efficiency.
2. Recommended workflow: Save the replacement templates in the text editor. Each time you write a blog post, paste the templates and follow the same steps.
3. Best use case: This approach is particularly useful for technical bloggers writing articles with many code blocks. I hope it helps you reduce repetitive manual work and write technical posts more efficiently.