Practice record of resolving instability problems in WordPress Gutenberg multi shortcode

The background

When writing a technical blog with a WordPress block editor (Gutenberg), I often need to include multiple code blocks in one article, such as:

SQL query (SQL)
Go sample code (GO)
PHP code (PHP)
Description text (Text)

Usually, an article will contain about 10 code blocks in combination.

This kind of content was very stable when I used the classic editor in the early days, but in Gutenberg, I encountered a typical problem:

Multiple SQL/GO/PHP shortCode parses exceptions occasionally when “Paste the whole article”

The problem phenomenon

When using SyntaxHighlighter Evolved, my writing style is usually:

Write a full article in a local txt file
Contains multiple SQL, GO, PHP blocks
Paste directly to WordPress

But in Gutenberg, the following phenomenon occurs:

❌ Abnormal situation
After the first release:
Some SQL blocks are resolved to code or <code>
Some shortcodes are not rendered correctly
Re-paste after editing the article again:
back to normal

This “first abnormal, second normal” behavior is very troublesome to write in batches.

The root cause analysis

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

Gutenberg behavioral features:

when you:

Paste the entire article with multiple shortcodes in one go

The system will:

Automatically identify shortcodes such as SQL and Go
Automatically split into multiple blocks
At the same time try to parse html/inline code
In some cases misjudgment of backticks (`) as inline code

lead to:

orders → orders
Escaped again → <code>orders</code>

4. Stable Writing Program (Core)

After many tests, the most stable method is:

❗ Don’t let Gutenberg “guess the block structure”, but fix the structure in advance

5. Compatibility scheme (for old writing or batch pasting)

In the case of SQL/GO/PHP shortcode (such as a historical article or a local TXT template), you can do the following:

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 in the local TXT at once, for example:

select count(*) from orders;

Explanatory text…

fmt.println("hello")

select * from users;

Step 3: Publish or Preview Validation

Check:

Is shortcode correctly parsed
Is CODE pollution
Is sql/go rendering normally?
⚠️ Notes

This method belongs to:

Compatible with old shortcode writing styles

It is not recommended for long-term use of new articles.

6. (Newly added) Modern recommendation plan (strongly recommended)
Step 1: Use SyntaxHighlighter Code Block

/syntax

Insert:

SyntaxHighlighter Evolved Code Block

Step 2: Paste code

For example:

fmt.println(“hello”)

Step 3: Select the language
sql
go
php
Advantage
No shortcode parsing problem
No code pollution
Full Gutenberg native support
more stable

7. Recommended writing specifications (long-term use)

In order to ensure the stability of the technical blog in the Gutenberg environment, it is recommended to unify the following specifications.

1. Code block specification (new standard recommended)

All new articles use SyntaxHighlighter Evolved’s Code Block (Gutenberg version):

| Type | Writing |
| — | ———————————
| SQL | SyntaxHighlighter Code Block + SQL |
| Go | SyntaxHighlighter Code Block + Go |
| PHP | SyntaxHighlighter Code Block + PHP |

No longer used as the main way:

...

...

For compatible only with historical articles.

2. Paste Specification

Recommended to use uniformly:

Ctrl + Shift + V (plain text paste)
or use Visual Studio Code as a transit editor

3. Block Specification (New Edition)

| Operation | Recommendation |
| ————————– | ———-
| SyntaxHighlighter Code Block | ✅ Recommended (Main Method) |
| shortcode block () | ⚠️ Only compatible |
| Paragraph Paste | ❌ Avoid |

8. Why is this plan more stable?

The core reason is:

1. No longer relying on Gutenberg automatic resolution

Avoid:

shortcode auto split error
First render exception

2. The code structure is controlled by block

WordPress Gutenberg directly uses:

Code block
SyntaxHighlighter Block

rather than shortcode inference

3. Avoid HTML pollution

Completely resolve:

code misunderstanding
<code>
backtick pollution

9. Summary (new version)

When writing a technical blog (SQL/GO/PHP mixed content) in Gutenberg environment, the core principles are upgraded to:

🧠 New Core Principles:

First use the block structure to ensure stable rendering, and then paste the content

Recommended process (final version)

1. Use SyntaxHighlighter Code Block (/Syntax)
2. Paste the entire article at one time (TXT)
3. Delete the automatically generated shortcode block
4. Keep Code Block rendering code
5. Preview preview check

10. Extension optimization (optional)

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

Prism highlight (more modern)
code copy button
Line number display optimization
The theme unified code style

11. Preview and bottom-up inspection before release (important)

After completing the article editing, it is still recommended to add a “Pre-release preview step” even if you have used the SyntaxHighLighter Code block (SQL/GO/PHP, etc.) according to the specification, which is used for the final base check.

In the Gutenberg editor of WordPress, you can preview the verification by previewing:

1. Use the preview function

Click before posting:

“Preview”
or “Preview in a new tab”

Confirm whether the page rendering effect is normal.

Focus check:

Does SQL still maintain the full structure
Whether there is code or <code> pollution
Is multiple SQL/GO/PHP rendering correctly?

2. Quick scroll check all code blocks

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

sql query whether the block is complete
Does the Go example wrap normally?
Whether the php code is not truncated
Text description is misplaced

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

3. How to deal with problems

If you find a problem in the preview:

Do not re-paste the whole article directly
Re-paste content for exceptions only for exceptional shortcode blocks
Preview again to confirm the repair result

4. Final Release Principles

Publish only after the preview confirms the following conditions:

All code blocks are rendered normally
No code or HTML escape pollution
Multilingual code block structure is consistent
The overall layout of the page is normal

5. The meaning of this step

The core function of this preview step is:

Intercept the occasional problems caused by Gutenberg’s automatic parsing before publishing

Compared with “repair after release”, the number of rework times can be significantly reduced, and the overall writing efficiency and stability can be significantly reduced.