Practical Record: Resolving Unstable Parsing of Multiple Shortcodes in WordPress Gutenberg

I. Background

When writing technical blog posts using the WordPress block editor (Gutenberg), I often need to include multiple types of code blocks in a single article, such as:

SQL queries (SQL)
Go example code (Go)
PHP code (PHP)
Explanatory text (Text)

Typically, an article will contain about 10 mixed code blocks.

In the early days of using the classic editor, this type of content was very stable, but in Gutenberg, I encountered a rather typical issue:

Multiple sql / go / php shortcodes occasionally parse abnormally when “pasting the entire article”

II. Problem Symptoms

When using SyntaxHighlighter Evolved, my writing workflow is usually:

Write the entire article in a local txt file
Include multiple sql, go, php blocks
Directly Ctrl + V paste into WordPress

However, the following issues occur in Gutenberg:

❌ Abnormal situations
After the first publication:
Some SQL blocks are parsed into code or <code>
Some shortcodes are not rendered correctly
After editing the article again and repasting:
Everything returns to normal

This “abnormal the first time, normal the second time” behavior is very frustrating for batch writing.

III. Root Cause Analysis

The essence of the problem lies not in the plugin, but in Gutenberg’s automatic parsing mechanism:

Gutenberg behavioral characteristics:

When you:

Paste an entire article containing multiple shortcodes all at once

The system will:

Automatically recognize shortcodes like sql, go
Automatically split them into multiple blocks
Simultaneously try to parse HTML / inline code
In some cases, misinterpret backticks (`) as inline code

Leading to:

orders → orders
Then being escaped → <code>orders</code>

IV. Stable Writing Solution (Core)

After multiple tests, the most stable method is:

❗ Do not let Gutenberg “guess the block structure”; instead, fix the structure in advance

V. Compatibility Solution (For Old Writing Methods or Batch Pasting)

If you are still using sql / go / php shortcodes (for example, in historical articles or local txt templates), you can adopt the following approach:

Step 1: Create a Shortcode block

In the WordPress Gutenberg editor:

Click “+ Add Block”
Select the Shortcode block
Step 2: Paste the entire article

Paste the full content from your local txt file all at once, for example:

[sql]
select count(*) from orders;
[/sql]

[sql]
select count(*) from orders;
[/sql]

Explanatory text…

[go]
fmt.Println("hello")
[/go]

[go]
fmt.Println("hello")
[/go]

[sql]
select * from users;
[/sql]

[sql]
select * from users;
[/sql]

Step 3: Publish or preview to verify

Check:

Whether shortcodes are parsed correctly
Whether code pollution occurs
Whether SQL / Go renders normally
⚠️ Notes

This approach is:

A compatible writing method for old shortcodes

Not recommended for long-term use in new articles.

VI. (New) Modern Recommended Solution (Highly Recommended)
Step 1: Use the SyntaxHighlighter Code Block

/syntax

Insert:

SyntaxHighlighter Evolved Code Block

Step 2: Paste the code

For example:

fmt.Println(“hello”)

Step 3: Select language
SQL
Go
PHP
Advantages
No shortcode parsing issues
No code pollution
Fully native Gutenberg support
More stable

VII. Recommended Writing Standards (For Long-Term Use)

To ensure the stability of technical blogs in the Gutenberg environment, it is recommended to standardize the following practices.

1. Code Block Standards (Recommended New Standard)

For all new articles, uniformly use the SyntaxHighlighter Evolved Code Block (Gutenberg version):

| Type | Syntax |
| — | ———————————- |
| SQL | SyntaxHighlighter Code Block + SQL |
| Go | SyntaxHighlighter Code Block + Go |
| PHP | SyntaxHighlighter Code Block + PHP |

No longer use as the primary method:

[sql]...[/sql]

[sql]...[/sql]

[go]...[/go]

[go]...[/go]

Only for historical article compatibility.

2. Pasting Standards

It is recommended to uniformly use:

Ctrl + Shift + V (Paste as plain text)
Or use Visual Studio Code as an intermediary editor

3. Block Standards (New Version)

| Operation | Recommended |
| —————————- | ——— |
| SyntaxHighlighter Code Block | ✅ Recommended (Primary method) |
| Shortcode block ([sql][/sql]) | ⚠️ Compatibility use only |
| Paragraph paste | ❌ Avoid |

VIII. Why This Solution Is More Stable

The core reason is:

1. No longer relies on Gutenberg’s automatic parsing

Avoiding:

Automatic shortcode splitting errors
First-render anomalies

2. Code structure is controlled by Blocks

WordPress Gutenberg directly uses:

Code Block
SyntaxHighlighter Block

Instead of shortcode inference

3. Avoids HTML pollution

Completely resolving:

code misinterpretation
<code>
Backtick pollution

IX. Summary (New Version)

When writing technical blogs (mixed SQL / Go / PHP content) in the Gutenberg environment, the core principle is upgraded to:

🧠 New core principle:

First use Block structure to ensure stable rendering, then paste content

Recommended workflow (Final version)

1. Use SyntaxHighlighter Code Block (/syntax)
2. Paste the entire article (txt) at once
3. Delete automatically generated Shortcode blocks
4. Keep Code Block to render code
5. Preview and check before publishing

X. Further Optimizations (Optional)

If you want to further optimize the experience later, you can consider:

Prism highlighting (more modern)
Code copy button
Line number display optimization
Unified theme code styling

XI. Pre-publish Preview and Fallback Check (Important)

After finishing editing an article, even if you have already followed the standard of using SyntaxHighlighter Code blocks (SQL / Go / PHP, etc.), it is still recommended to add a “pre-publish preview step” for a final fallback check.

In the WordPress Gutenberg editor, you can perform preview verification via the following methods:

1. Use the preview function

Before publishing, click:

“Preview”
Or “Preview in new tab”

Confirm whether the page rendering effect is normal.

Key checks:

Whether SQL still maintains its complete structure
Whether code or <code> pollution appears
Whether multiple sql / go / php blocks render correctly

2. Quickly scroll to check all code blocks

For a technical article containing about 10 code blocks, it is recommended to quickly check on the preview page:

Whether SQL query blocks are complete
Whether Go examples wrap normally
Whether PHP code is truncated
Whether text explanations are misplaced

This process usually takes only 10 to 20 seconds, but it can effectively avoid rework after publishing.

3. How to handle discovered issues

If issues are found during the preview:

Do not directly repaste the entire article
Only repaste content for the abnormal shortcode blocks
Preview again to confirm the fix results

4. Final publishing principle

Only publish after the preview confirms the following conditions:

All code blocks render normally
No code or HTML escape pollution
Consistent multi-language code block structure
Overall page layout is normal

5. The significance of this step

The core role of this preview step is:

To intercept sporadic issues caused by Gutenberg’s automatic parsing before publishing

Compared to “fixing after publishing,” this can significantly reduce the number of reworks, improving overall writing efficiency and stability.