While organizing legacy WordPress posts recently, I ran into a Mermaid flowchart syntax issue.
The flowcharts in the article had been migrated to a MerPress Mermaid block, but they were not rendering correctly on the front end. Instead, the following appeared directly:
Syntax error in text
mermaid version 11.9.0
Syntax error in text, and the Mermaid version is 11.9.0At first, I thought the flowchart declaration was simply written incorrectly, but my actual troubleshooting revealed that the real key issue was not just on the first line.
The ultimately effective solution was:
A["节点文本"]
instead of:
A[节点文本]
This distinction is especially important when nodes contain function names like test(), main(), and go test(), as well as mixed Chinese and English text.
1. The first issue discovered: 流程图 TD
In the original Mermaid content, the first line was written as:
流程图 TD
This is, of course, not a valid Mermaid flowchart declaration.
Mermaid should use:
flowchart TD
or:
graph TD
So initially I changed:
流程图 TD
to:
flowchart TD
For example, the original code:
流程图 TD
A[程序启动] --> B[主协程启动，执行go test()]
B --> C[子协程test()启动，就绪态]
B --> D[主协程执行自身for循环]
was modified to:
flowchart TD
A[程序启动] --> B[主协程启动，执行go test()]
B --> C[子协程test()启动，就绪态]
B --> D[主协程执行自身for循环]
This modification itself was correct.
However, after saving and checking the front end again, the result was still:
Syntax error in text
mermaid version 11.9.0
In other words:
流程图 TD was indeed problematic, but it was not the only issue in this flowchart.
2. flowchart TD is now correct, so why is it still throwing an error?
Continuing to look at the flowchart code, I noticed that many nodes used this format:
B[主协程启动，执行go test()]
and:
C[子协程test()启动，就绪态]
as well as in other scenarios:
B[主协程启动，执行test()（无go关键字）]
C[test()输出hello,world 1]
H[main()输出hello:golang 1]
These node texts mixed:
test()
main()
go test()
along with:
- Chinese characters;
- English half-width parentheses
(); - Chinese parentheses
（）; - commas;
- colons;
- numbers;
- English function names.
At this point, continuing to focus only on:
flowchart TD
was no longer meaningful.
What really needed to be addressed was:
the node text formatting.
3. The truly effective solution: A["节点文本"]
The final approach I took was very simple:
Change:
A[节点文本]
uniformly to:
A["节点文本"]
For example:
B[主协程启动，执行go test()]
was modified to:
B["主协程启动，执行go test()"]
The original:
C[子协程test()启动，就绪态]
was modified to:
C["子协程test()启动，就绪态"]
As another example:
B[主协程启动，执行test()（无go关键字）]
was modified to:
B["主协程启动，执行test()（无go关键字）"]
This was the most crucial fix for this Syntax error in text issue.
In other words, this issue can be summarized very simply as changing:
A[节点文本]
to:
A["节点文本"]
4. Complete repaired Mermaid example
Using one of the goroutine execution flowcharts as an example, the original code was roughly:
flowchart TD
A[程序启动] --> B[主协程启动，执行go test()]
B --> C[子协程test()启动，进入就绪态]
B --> D[主协程继续执行自身for循环]
C --> E[子协程输出hello,world 1]
D --> F[主协程输出hello:golang 1]
E --> G[子协程休眠1秒，让出CPU，进入等待态]
F --> H[主协程休眠1秒，让出CPU，进入等待态]
G --> I[子协程休眠结束，进入就绪态，等待调度]
H --> J[主协程休眠结束，进入就绪态，等待调度]
I --> K[调度器分配执行权，子协程输出hello,world 2]
J --> L[调度器分配执行权，主协程输出hello:golang 2]
K --> M[子协程休眠1秒]
L --> N[主协程休眠1秒]
M --> O[重复执行，直到两者都执行10次]
N --> O
O --> P[主协程执行完毕，退出]
O --> Q[子协程执行完毕，退出]
P --> R[程序终止]
Q --> R
It was finally modified to:
flowchart TD
A["程序启动"] --> B["主协程启动，执行go test()"]
B --> C["子协程test()启动，进入就绪态"]
B --> D["主协程继续执行自身for循环"]
C --> E["子协程输出hello,world 1"]
D --> F["主协程输出hello:golang 1"]
E --> G["子协程休眠1秒，让出CPU，进入等待态"]
F --> H["主协程休眠1秒，让出CPU，进入等待态"]
G --> I["子协程休眠结束，进入就绪态，等待调度"]
H --> J["主协程休眠结束，进入就绪态，等待调度"]
I --> K["调度器分配执行权，子协程输出hello,world 2"]
J --> L["调度器分配执行权，主协程输出hello:golang 2"]
K --> M["子协程休眠1秒"]
L --> N["主协程休眠1秒"]
M --> O["重复执行，直到两者都执行10次"]
N --> O
O --> P["主协程执行完毕，退出"]
O --> Q["子协程执行完毕，退出"]
P --> R["程序终止"]
Q --> R
After the modifications were completed, the flowchart finally rendered correctly.
5. Why I will prioritize using A["节点文本"] from now on
Strictly speaking, not all Mermaid nodes must be written as:
A["节点文本"]
Some simple nodes, such as:
A[程序启动]
might parse correctly on their own.
However, for a technical blog, flowchart nodes often contain:
test()
main()
time.Sleep()
go test()
runtime.Gosched()
hello,world
hello:golang
along with mixed Chinese descriptions.
Having to judge every time:
- which parenthesis might cause an issue;
- which punctuation needs escaping;
- which combination Mermaid 11.9.0 can accept properly;
- and which combination might trigger a parsing error;
is unnecessary.
For standard text rectangle nodes, I prefer to just uniformly write them as:
A["节点文本"]
For example:
A["程序启动"]
B["主协程启动，执行go test()"]
C["子协程test()启动，就绪态"]
D["主协程执行自身for循环"]
This is much simpler.
6. Why I later processed the entire WordPress source code
At the time, this article did not just have one Mermaid flowchart; there were multiple MerPress Mermaid blocks.
Since the repair rule was already established as changing:
A[节点文本]
to:
A["节点文本"]
opening each flowchart one by one in the WordPress editor to modify them line by line would have been cumbersome and prone to missing a node.
So later, I directly copied the entire Gutenberg source code from the WordPress source code editor and handed it over to ChatGPT for one-pass processing.
A special note here:
Copying the entire Gutenberg source code was not a necessary step to fix the Mermaid errors.
It was only to:
modify all Mermaid flowcharts in the article at once, since I already knew how to fix them.
If an article only has one flowchart, you can simply modify it directly in the Mermaid block from:
A[节点文本]
to:
A["节点文本"]
There is no need to process the entire WordPress source code.
7. The actual troubleshooting sequence for this issue
Looking back at the whole process, here is what actually happened:
The front end displayed:
Syntax error in text
mermaid version 11.9.0
First, I discovered:
流程图 TD
So I changed it to:
flowchart TD
But it still threw an error.
Then I continued checking the nodes and found that:
B[主协程启动，执行go test()]
these types of nodes existed in large numbers.
Finally, I uniformly changed them to:
B["主协程启动，执行go test()"]
and the flowchart returned to normal.
So the issue this time was not:
flowchart TDwas written incorrectly.
To be precise, it should be stated as:
The Mermaid source code had multiple syntax compatibility issues. After fixing the flowchart declaration, the node text still caused parsing failures; this was ultimately resolved by uniformly adding double quotes to the node text.
8. How I will handle Syntax error in text in the future
If I see:
Syntax error in text
again, I should still first check the flowchart declaration:
flowchart TD
or:
flowchart LR
to see if it is correct.
Next, I will check:
[]
()
{}
to see if any of these parentheses are incomplete.
Then I will focus on the node text.
For example, if I encounter:
A[test()]
B[执行go test()]
C[main()执行结束]
I will prioritize directly changing them to:
A["test()"]
B["执行go test()"]
C["main()执行结束"]
For standard text nodes in a technical blog, this can serve as a practical default rule.
9. This also supplements my legacy article migration rules
I encountered this issue while handling the format migration of legacy WordPress articles.
In the past, many flowcharts, terminal outputs, code snippets, and explanatory content were placed in legacy code blocks like SyntaxHighlighter.
During migration, not all content should be mechanically converted to Code Block Pro.
For example, actual flowchart content is better suited for conversion to:
MerPress / Mermaid
Therefore, migration validation cannot simply require:
Original SyntaxHighlighter count
=
New Code Block Pro count
A more reasonable minimum requirement should be:
SyntaxHighlighter = 0
The original content can be migrated into different formats based on its actual type:
Code Block Pro
Mermaid
Standard paragraphs
Other more appropriate Gutenberg blocks
But for Mermaid, an additional validation condition is needed:
It is not enough for the block to merely exist; the Mermaid source code must actually render.
Because:
<!-- wp:merpress/mermaidjs -->
Its existence only indicates that the Gutenberg block was created successfully.
If there are issues with the internal source code, the front end will still display:
Syntax error in text
So future Mermaid migration validation should include:
Mermaid block exists
+
Source code structure is correct
+
Front end renders normally
10. Summary
The error encountered this time was:
Syntax error in text
mermaid version 11.9.0
Initially, I found that the first line of the flowchart was written as:
流程图 TD
I changed it to:
flowchart TD
After that, the error persisted.
Upon further inspection, I finally determined that the truly effective solution was to change:
A[节点文本]
to:
A["节点文本"]
Especially when nodes contain:
test()
main()
go test()
time.Sleep()
or mixed Chinese and English text, parentheses, and punctuation, uniformly using double quotes is much safer.
So the most important takeaway this time is not the complex troubleshooting process, but simply this one rule:
flowchart TD
A["节点文本"]
instead of:
flowchart TD
A[节点文本]
The reason I later copied out the entire Gutenberg source code for processing was simply because the article contained multiple Mermaid flowcharts, making it convenient to modify them all at once; it was not a required step to resolve the issue.
Ultimately, the repaired flowcharts are now able to display correctly.
Figure 3: The finally repaired Mermaid 11.9.0 flowchart renders normally, and Syntax error in text no longer appears.
This also adds a very practical lesson for future legacy WordPress article migrations:
Prioritize using A["节点文本"] for standard Mermaid text nodes; do not wait for syntax errors to appear on the front end before dealing with them one by one.