diff --git a/Project.toml b/Project.toml
index 5c74d41..075c587 100644
--- a/Project.toml
+++ b/Project.toml
@@ -20,7 +20,7 @@ KernelDensity = "0.6"
 Makie = "0.20, 0.21, 0.22"
 StatsBase = "0.34"
 julia = "1.9"
-AlgebraOfGraphics = "0.8"
+AlgebraOfGraphics = "0.9.5"
 
 [extras]
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
diff --git a/docs/package.json b/docs/package.json
index 71458cb..0ed8718 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -1,18 +1,15 @@
 {
-  "devDependencies": {
-    "markdown-it": "^14.0.0",
-    "markdown-it-mathjax3": "^4.3.2",
-    "vitepress": "^1.0.0-rc.43",
-    "vitepress-plugin-tabs": "^0.5.0",
-    "vitest": "^1.3.0"
-  },
   "scripts": {
     "docs:dev": "vitepress dev build/.documenter",
     "docs:build": "vitepress build build/.documenter",
     "docs:preview": "vitepress preview build/.documenter"
   },
   "dependencies": {
-    "@shikijs/transformers": "^1.1.7",
-    "markdown-it-footnote": "^4.0.0"
+    "@nolebase/vitepress-plugin-enhanced-readabilities": "^2.14.0",
+    "markdown-it": "^14.1.0",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it-mathjax3": "^4.3.2",
+    "vitepress": "^1.6.3",
+    "vitepress-plugin-tabs": "^0.6.0"
   }
 }
diff --git a/ext/AlgebraOfGraphicsExt.jl b/ext/AlgebraOfGraphicsExt.jl
index 50b2bce..3c2db7c 100644
--- a/ext/AlgebraOfGraphicsExt.jl
+++ b/ext/AlgebraOfGraphicsExt.jl
@@ -2,6 +2,7 @@ module AlgebraOfGraphicsExt
 using SwarmMakie, AlgebraOfGraphics, Makie
 import AlgebraOfGraphics as AOG
 
+# Define the "aesthetic mapping" - which kwargs go where
 function AlgebraOfGraphics.aesthetic_mapping(::Type{Beeswarm}, ::AOG.Normal, ::AOG.Normal)
     AOG.dictionary([
         1 => AOG.AesX,
@@ -13,9 +14,14 @@ function AlgebraOfGraphics.aesthetic_mapping(::Type{Beeswarm}, ::AOG.Normal, ::A
     ])
 end
 
-
+# Define the legend elements (scatter, in this case)
 function AOG.legend_elements(T::Type{Beeswarm}, attributes, scale_args::AOG.MixedArguments)
     return AOG.legend_elements(Makie.Scatter, attributes, scale_args) # same legend as Scatter
 end
 
+# Instruct AoG to always merge all beeswarm plots in the same layer 
+# This means that if a `color` with 2 unique values is given, 
+# then only one beeswarm plot object is created (not two).
+AOG.mergeable(::Type{<: Beeswarm}, primary) = true
+
 end