docs: add nested namespace documentation and changeset

Co-Authored-By: Claude Opus 4.6 (prompted with care by @M-a-c)

Author: M-a-c

.changeset/feat-nested-namespaces.md

@@ -0,0 +1,5 @@
+---
+'mermaid': minor
+---
+
+feat: add nested namespace support for class diagrams via dot notation and syntactic nesting

docs/syntax/classDiagram.md

@@ -498,6 +498,104 @@ namespace BaseShapes {
 }
 ```
 
+### Nested Namespaces (v\<MERMAID_RELEASE_VERSION>+)
+
+Namespaces can be nested to represent hierarchical groupings. There are two ways to define nested namespaces:
+
+**Dot notation** creates intermediate namespaces automatically:
+
+```mermaid-example
+classDiagram
+    namespace Company.Engineering.Backend {
+        class Developer {
+            +writeCode()
+        }
+    }
+    namespace Company.Engineering.Frontend {
+        class Designer {
+            +createMockup()
+        }
+    }
+    namespace Company.Engineering {
+        class TechLead {
+            +planSprint()
+        }
+    }
+    TechLead --> Developer : leads
+    TechLead --> Designer : leads
+```
+
+```mermaid
+classDiagram
+    namespace Company.Engineering.Backend {
+        class Developer {
+            +writeCode()
+        }
+    }
+    namespace Company.Engineering.Frontend {
+        class Designer {
+            +createMockup()
+        }
+    }
+    namespace Company.Engineering {
+        class TechLead {
+            +planSprint()
+        }
+    }
+    TechLead --> Developer : leads
+    TechLead --> Designer : leads
+```
+
+**Syntactic nesting** places namespace blocks inside other namespace blocks:
+
+```mermaid-example
+classDiagram
+    namespace Platform {
+        namespace Auth {
+            class UserService {
+                +login()
+                +logout()
+            }
+        }
+        namespace Data {
+            class Repository {
+                +find()
+                +save()
+            }
+        }
+        class Gateway {
+            +route()
+        }
+    }
+    Gateway --> UserService : delegates
+    Gateway --> Repository : delegates
+```
+
+```mermaid
+classDiagram
+    namespace Platform {
+        namespace Auth {
+            class UserService {
+                +login()
+                +logout()
+            }
+        }
+        namespace Data {
+            class Repository {
+                +find()
+                +save()
+            }
+        }
+        class Gateway {
+            +route()
+        }
+    }
+    Gateway --> UserService : delegates
+    Gateway --> Repository : delegates
+```
+
+Both approaches can be combined. Dot notation like `namespace A.B.C` will automatically create namespaces `A` and `A.B` as parents if they don't already exist.
+
 ## Cardinality / Multiplicity on relations
 
 Multiplicity or cardinality in class diagrams indicates the number of instances of one class that can be linked to an instance of the other class. For example, each company will have one or more employees (not zero), and each employee currently works for zero or one companies.

packages/mermaid/src/docs/syntax/classDiagram.md

@@ -320,6 +320,60 @@ namespace BaseShapes {
 }
 ```
 
+### Nested Namespaces (v<MERMAID_RELEASE_VERSION>+)
+
+Namespaces can be nested to represent hierarchical groupings. There are two ways to define nested namespaces:
+
+**Dot notation** creates intermediate namespaces automatically:
+
+```mermaid-example
+classDiagram
+    namespace Company.Engineering.Backend {
+        class Developer {
+            +writeCode()
+        }
+    }
+    namespace Company.Engineering.Frontend {
+        class Designer {
+            +createMockup()
+        }
+    }
+    namespace Company.Engineering {
+        class TechLead {
+            +planSprint()
+        }
+    }
+    TechLead --> Developer : leads
+    TechLead --> Designer : leads
+```
+
+**Syntactic nesting** places namespace blocks inside other namespace blocks:
+
+```mermaid-example
+classDiagram
+    namespace Platform {
+        namespace Auth {
+            class UserService {
+                +login()
+                +logout()
+            }
+        }
+        namespace Data {
+            class Repository {
+                +find()
+                +save()
+            }
+        }
+        class Gateway {
+            +route()
+        }
+    }
+    Gateway --> UserService : delegates
+    Gateway --> Repository : delegates
+```
+
+Both approaches can be combined. Dot notation like `namespace A.B.C` will automatically create namespaces `A` and `A.B` as parents if they don't already exist.
+
 ## Cardinality / Multiplicity on relations
 
 Multiplicity or cardinality in class diagrams indicates the number of instances of one class that can be linked to an instance of the other class. For example, each company will have one or more employees (not zero), and each employee currently works for zero or one companies.