diff --git a/packages/mermaid/src/docs/syntax/sankey.md b/packages/mermaid/src/docs/syntax/sankey.md
index a6aa8e5a9..66c8a742f 100644
--- a/packages/mermaid/src/docs/syntax/sankey.md
+++ b/packages/mermaid/src/docs/syntax/sankey.md
@@ -1,87 +1,16 @@
 # Sankey diagrams
 
 > A sankey diagram is a visualization used to depict a flow from one set of values to another.
-> This is an experimental diagram. Its syntax are very close to plain CSV, but highly likely
-> to be extended in the nearest future.
+
+::: warning
+This is an experimental diagram. Its syntax are very close to plain CSV, but it is to be extended in the nearest future.
+:::
 
 The things being connected are called nodes and the connections are called links.
 
 ## Example
 
-Code:
-
-```mermaid-example
-sankey-beta
-
-Agricultural 'waste',Bio-conversion,124.729
-Bio-conversion,Liquid,0.597
-Bio-conversion,Losses,26.862
-Bio-conversion,Solid,280.322
-Bio-conversion,Gas,81.144
-Biofuel imports,Liquid,35
-Biomass imports,Solid,35
-Coal imports,Coal,11.606
-Coal reserves,Coal,63.965
-Coal,Solid,75.571
-District heating,Industry,10.639
-District heating,Heating and cooling - commercial,22.505
-District heating,Heating and cooling - homes,46.184
-Electricity grid,Over generation / exports,104.453
-Electricity grid,Heating and cooling - homes,113.726
-Electricity grid,H2 conversion,27.14
-Electricity grid,Industry,342.165
-Electricity grid,Road transport,37.797
-Electricity grid,Agriculture,4.412
-Electricity grid,Heating and cooling - commercial,40.858
-Electricity grid,Losses,56.691
-Electricity grid,Rail transport,7.863
-Electricity grid,Lighting & appliances - commercial,90.008
-Electricity grid,Lighting & appliances - homes,93.494
-Gas imports,Ngas,40.719
-Gas reserves,Ngas,82.233
-Gas,Heating and cooling - commercial,0.129
-Gas,Losses,1.401
-Gas,Thermal generation,151.891
-Gas,Agriculture,2.096
-Gas,Industry,48.58
-Geothermal,Electricity grid,7.013
-H2 conversion,H2,20.897
-H2 conversion,Losses,6.242
-H2,Road transport,20.897
-Hydro,Electricity grid,6.995
-Liquid,Industry,121.066
-Liquid,International shipping,128.69
-Liquid,Road transport,135.835
-Liquid,Domestic aviation,14.458
-Liquid,International aviation,206.267
-Liquid,Agriculture,3.64
-Liquid,National navigation,33.218
-Liquid,Rail transport,4.413
-Marine algae,Bio-conversion,4.375
-Ngas,Gas,122.952
-Nuclear,Thermal generation,839.978
-Oil imports,Oil,504.287
-Oil reserves,Oil,107.703
-Oil,Liquid,611.99
-Other waste,Solid,56.587
-Other waste,Bio-conversion,77.81
-Pumped heat,Heating and cooling - homes,193.026
-Pumped heat,Heating and cooling - commercial,70.672
-Solar PV,Electricity grid,59.901
-Solar Thermal,Heating and cooling - homes,19.263
-Solar,Solar Thermal,19.263
-Solar,Solar PV,59.901
-Solid,Agriculture,0.882
-Solid,Thermal generation,400.12
-Solid,Industry,46.477
-Thermal generation,Electricity grid,525.531
-Thermal generation,Losses,787.129
-Thermal generation,District heating,79.329
-Tidal,Electricity grid,9.452
-UK land based bioenergy,Bio-conversion,182.01
-Wave,Electricity grid,19.013
-Wind,Electricity grid,289.366
-```
+This example taken from [observable](https://observablehq.com/@d3/sankey/2?collection=@d3/d3-sankey). It may be rendered a little bit differently, though, in terms of size and colors.
 
 ```mermaid
 sankey-beta
@@ -156,29 +85,177 @@ Wave,Electricity grid,19.013
 Wind,Electricity grid,289.366
 ```
 
-## Syntax
-
-The idea behind it is that a user types `sankey-beta` first, then pastes raw CSV below and get the result.
-
-It is implemented according CSV standard as [described here](https://www.ietf.org/rfc/rfc4180.txt) with subtle differences:
-
-- CSV must contain 3 columns only
-- It is allowed to have empty lines without comma separators for visual purposes
+::: details
 
 ```mermaid-example
 sankey-beta
 
 Agricultural 'waste',Bio-conversion,124.729
-
-%% 
 Bio-conversion,Liquid,0.597
 Bio-conversion,Losses,26.862
+Bio-conversion,Solid,280.322
+Bio-conversion,Gas,81.144
+Biofuel imports,Liquid,35
+Biomass imports,Solid,35
+Coal imports,Coal,11.606
+Coal reserves,Coal,63.965
+Coal,Solid,75.571
+District heating,Industry,10.639
+District heating,Heating and cooling - commercial,22.505
+District heating,Heating and cooling - homes,46.184
+Electricity grid,Over generation / exports,104.453
+Electricity grid,Heating and cooling - homes,113.726
+Electricity grid,H2 conversion,27.14
+Electricity grid,Industry,342.165
+Electricity grid,Road transport,37.797
+Electricity grid,Agriculture,4.412
+Electricity grid,Heating and cooling - commercial,40.858
+Electricity grid,Losses,56.691
+Electricity grid,Rail transport,7.863
+Electricity grid,Lighting & appliances - commercial,90.008
+Electricity grid,Lighting & appliances - homes,93.494
+Gas imports,Ngas,40.719
+Gas reserves,Ngas,82.233
+Gas,Heating and cooling - commercial,0.129
+Gas,Losses,1.401
+Gas,Thermal generation,151.891
+Gas,Agriculture,2.096
+Gas,Industry,48.58
+Geothermal,Electricity grid,7.013
+H2 conversion,H2,20.897
+H2 conversion,Losses,6.242
+H2,Road transport,20.897
+Hydro,Electricity grid,6.995
+Liquid,Industry,121.066
+Liquid,International shipping,128.69
+Liquid,Road transport,135.835
+Liquid,Domestic aviation,14.458
+Liquid,International aviation,206.267
+Liquid,Agriculture,3.64
+Liquid,National navigation,33.218
+Liquid,Rail transport,4.413
+Marine algae,Bio-conversion,4.375
+Ngas,Gas,122.952
+Nuclear,Thermal generation,839.978
+Oil imports,Oil,504.287
+Oil reserves,Oil,107.703
+Oil,Liquid,611.99
+Other waste,Solid,56.587
+Other waste,Bio-conversion,77.81
+Pumped heat,Heating and cooling - homes,193.026
+Pumped heat,Heating and cooling - commercial,70.672
+Solar PV,Electricity grid,59.901
+Solar Thermal,Heating and cooling - homes,19.263
+Solar,Solar Thermal,19.263
+Solar,Solar PV,59.901
+Solid,Agriculture,0.882
+Solid,Thermal generation,400.12
+Solid,Industry,46.477
+Thermal generation,Electricity grid,525.531
+Thermal generation,Losses,787.129
+Thermal generation,District heating,79.329
+Tidal,Electricity grid,9.452
+UK land based bioenergy,Bio-conversion,182.01
+Wave,Electricity grid,19.013
+Wind,Electricity grid,289.366
+```
+:::
+
+
+## Syntax
+
+The idea behind syntax is that a user types `sankey-beta` keyword first, then pastes raw CSV below and get the result.
+
+It is implements standard as [described here](https://www.ietf.org/rfc/rfc4180.txt) with subtle **differences**:
+
+- CSV must contain **3 columns only**
+- It is **allowed** to have **empty lines** without comma separators for visual purposes
+
+### Empty lines
+
+CSV does not support empty lines (without comma delimeters) by default. But you can add them if needed.
+
+```mermaid-example
+sankey-beta
+
+Bio-conversion,Liquid,0.597
+Bio-conversion,Losses,26.862
+
 Bio-conversion,Solid,280.322
 Bio-conversion,Gas,81.144
 ```
 
-If you need your title to have a comma, wrap it in double quotes
+```mermaid
+sankey-beta
 
+Bio-conversion,Liquid,0.597
+Bio-conversion,Losses,26.862
 
-"Hello, Mister Anderson"
+Bio-conversion,Solid,280.322
+Bio-conversion,Gas,81.144
+```
 
+### Commas
+
+If you need to have a comma, wrap it in double quotes:
+
+```mermaid-example
+sankey-beta
+
+Pumped heat,"Heating and cooling, homes",193.026
+Pumped heat,"Heating and cooling, commercial",70.672
+```
+
+```mermaid
+sankey-beta
+
+Pumped heat,"Heating and cooling, homes",193.026
+Pumped heat,"Heating and cooling, commercial",70.672
+```
+
+### Double quotes
+If you need to have double quote, put a pair of them:
+
+```mermaid-example
+sankey-beta
+
+Pumped heat,"Heating and cooling ""homes""",193.026
+Pumped heat,"Heating and cooling, ""commercial""",70.672
+```
+
+```mermaid
+sankey-beta
+
+Pumped heat,"Heating and cooling ""homes""",193.026
+Pumped heat,"Heating and cooling, ""commercial""",70.672
+```
+
+### Coloring and Фlignment
+
+You can change graph layout by setting `nodeAlignment` to:
+
+* `justify`
+* `center`
+* `left`
+* `right`
+
+And adjust coloring of the links by setting `linkColor` to one of those:
+
+* `source`
+* `target`
+* `gradient`
+* hex code of color, like `#a1a1a1`
+
+```html
+  <script>
+    const config = {
+      startOnLoad: true,
+      securityLevel: "loose",
+      sankey: {
+        linkColor: "source",
+        nodeAlignment: "left"
+      }
+    };
+    mermaid.initialize(config);
+  </script>
+```
\ No newline at end of file
diff --git a/run b/run
index ecc6bb02b..88af16418 100755
--- a/run
+++ b/run
@@ -24,6 +24,8 @@ $RUN --service-ports mermaid sh -c "cd packages/mermaid/src/docs && npx pnpm pre
 ;;
 
 help)
+
+# Alignment of help message must be as it is, it will be nice looking when printed
 usage=$(
 cat <<EOF
 Run commands within docker containers.
@@ -48,7 +50,7 @@ Examples of frequiently used commands:
 
 $name pnpm add                # Add package, 'run add d3-sankey'
 $name pnpm prettier --write   # Prettify a file 'run prettier <path-to-file>'
-                              #   git diff --name-only develop | xargs run pnpm prettier --write
+                            #   git diff --name-only develop | xargs run pnpm prettier --write
 $name pnpm test               # Run unit tests
 $name pnpm vitest             # Run watcher for unit tests
 $name pnpm e2e                # Run integration tests