From 494c7294cbf32b5c7ac2111bbc5b1430a1cb13ac Mon Sep 17 00:00:00 2001
From: darshanr0107 <darshan@mermaidchart.com>
Date: Tue, 2 Sep 2025 15:13:45 +0530
Subject: [PATCH] chore: address review comments related to documentation

on-behalf-of: @Mermaid-Chart <hello@mermaidchart.com>
---
 docs/config/layouts.md                        | 10 ++-
 docs/config/tidy-tree.md                      | 76 +++++++++++++------
 packages/mermaid/src/docs/config/layouts.md   |  5 +-
 packages/mermaid/src/docs/config/tidy-tree.md | 44 +++++------
 4 files changed, 85 insertions(+), 50 deletions(-)

diff --git a/docs/config/layouts.md b/docs/config/layouts.md
index ff5607629..18e9c9423 100644
--- a/docs/config/layouts.md
+++ b/docs/config/layouts.md
@@ -20,14 +20,20 @@ This page lists the available layout algorithms supported in Mermaid diagrams.
 You can specify the layout in your diagram's YAML config or initialization options. For example:
 
 ```mermaid-example
-%%{init: { 'layout': 'elk' }}%%
+---
+config:
+  layout: elk
+---
 graph TD;
   A-->B;
   B-->C;
 ```
 
 ```mermaid
-%%{init: { 'layout': 'elk' }}%%
+---
+config:
+  layout: elk
+---
 graph TD;
   A-->B;
   B-->C;
diff --git a/docs/config/tidy-tree.md b/docs/config/tidy-tree.md
index a1105b780..1d4227596 100644
--- a/docs/config/tidy-tree.md
+++ b/docs/config/tidy-tree.md
@@ -16,7 +16,7 @@ The **tidy-tree** layout arranges nodes in a hierarchical, tree-like structure.
 
 ## Example Usage
 
-```
+```mermaid-example
 ---
 config:
   layout: tidy-tree
@@ -29,29 +29,59 @@ root((mindmap is a long thing))
   D
 ```
 
+```mermaid
+---
+config:
+  layout: tidy-tree
+---
+mindmap
+root((mindmap is a long thing))
+  A
+  B
+  C
+  D
 ```
- ---
-      config:
-        layout: tidy-tree
-      ---
-      mindmap
-      root((mindmap))
-        Origins
-          Long history
-          ::icon(fa fa-book)
-          Popularisation
-            British popular psychology author Tony Buzan
-        Research
-          On effectiveness&lt;br/>and features
-          On Automatic creation
-            Uses
-                Creative techniques
-                Strategic planning
-                Argument mapping
-        Tools
-              id)I am a cloud(
-                  id))I am a bang((
-                    Tools
+
+```mermaid-example
+---
+config:
+  layout: tidy-tree
+---
+mindmap
+root((mindmap))
+    Origins
+      Long history
+      ::icon(fa fa-book)
+      Popularisation
+        British popular psychology author Tony Buzan
+    Research
+      On effectiveness<br/>and features
+      On Automatic creation
+        Uses
+            Creative techniques
+            Strategic planning
+            Argument mapping
+```
+
+```mermaid
+---
+config:
+  layout: tidy-tree
+---
+mindmap
+root((mindmap))
+    Origins
+      Long history
+      ::icon(fa fa-book)
+      Popularisation
+        British popular psychology author Tony Buzan
+    Research
+      On effectiveness<br/>and features
+      On Automatic creation
+        Uses
+            Creative techniques
+            Strategic planning
+            Argument mapping
 ```
 
 ## Note
diff --git a/packages/mermaid/src/docs/config/layouts.md b/packages/mermaid/src/docs/config/layouts.md
index 743b7dd9a..56f5072f6 100644
--- a/packages/mermaid/src/docs/config/layouts.md
+++ b/packages/mermaid/src/docs/config/layouts.md
@@ -14,7 +14,10 @@ This page lists the available layout algorithms supported in Mermaid diagrams.
 You can specify the layout in your diagram's YAML config or initialization options. For example:
 
 ```mermaid
-%%{init: { 'layout': 'elk' }}%%
+---
+config:
+  layout: elk
+---
 graph TD;
   A-->B;
   B-->C;
diff --git a/packages/mermaid/src/docs/config/tidy-tree.md b/packages/mermaid/src/docs/config/tidy-tree.md
index 0a617ac96..f98d36379 100644
--- a/packages/mermaid/src/docs/config/tidy-tree.md
+++ b/packages/mermaid/src/docs/config/tidy-tree.md
@@ -10,7 +10,7 @@ The **tidy-tree** layout arranges nodes in a hierarchical, tree-like structure.
 
 ## Example Usage
 
-```
+```mermaid-example
 ---
 config:
   layout: tidy-tree
@@ -23,29 +23,25 @@ root((mindmap is a long thing))
   D
 ```
 
-```
- ---
-      config:
-        layout: tidy-tree
-      ---
-      mindmap
-      root((mindmap))
-        Origins
-          Long history
-          ::icon(fa fa-book)
-          Popularisation
-            British popular psychology author Tony Buzan
-        Research
-          On effectiveness&lt;br/>and features
-          On Automatic creation
-            Uses
-                Creative techniques
-                Strategic planning
-                Argument mapping
-        Tools
-              id)I am a cloud(
-                  id))I am a bang((
-                    Tools
+```mermaid-example
+---
+config:
+  layout: tidy-tree
+---
+mindmap
+root((mindmap))
+    Origins
+      Long history
+      ::icon(fa fa-book)
+      Popularisation
+        British popular psychology author Tony Buzan
+    Research
+      On effectiveness<br/>and features
+      On Automatic creation
+        Uses
+            Creative techniques
+            Strategic planning
+            Argument mapping
 ```
 
 ## Note