diff --git a/doc/MAPGEN.md b/doc/MAPGEN.md
index 0970b993b258d..94e7c2e056ac9 100644
--- a/doc/MAPGEN.md
+++ b/doc/MAPGEN.md
@@ -994,6 +994,29 @@ an `update_mapgen`, as normal mapgen can just specify the terrain directly.
 
 - "transform": (required, string) the id of the `ter_furn_transform` to run.
 
+### Spawn nested chunks based on overmap neighbors with "place_nested"
+
+Place_nested allows for limited conditional spawning of chunks based on the `"id"`s of their overmap neighbors.  This is useful for creating smoother transitions between biome types or to dynamically create walls at the edges of a mutable structure.
+
+| Field              | Description
+| ---                | ---
+| chunks/else_chunks | (required, string) the nested_mapgen_id of the chunk that will be conditionally placed. Chunks are placed if the specified neighbor matches, and "else_chunks" otherwise.  
+| x and y            | (required, int) the cardinal position in which the chunk will be placed. 
+| neighbors          | (optional, string ) Any of the neighboring overmaps that should be evaluated before placing the chunk. Despite the plural field name, only a single neighbor direction can be evaluated per chunk.  The direction itself can check for any amount of overmap `"id"` substrings.
+|
+
+The following adjacent overmaps can be evaluated in this manner: the direct cardinal neighbors ( `"north", "east", "south", "west"` ) the inter cardinal neighbors ( `"north_east", "north_west", "south_east", "south_west"` ), and the direct vertical neighbors ( `"above", "below"` ).
+
+Example:
+
+```json
+      "place_nested": [
+        { "chunks": [ "concrete_wall_ew" ], "x": 0, "y": 0, "neighbors": { "north": [ "empty_rock", "field" ] } },
+        { "else_chunks": [ "concrete_wall_ns" ], "x": 0, "y": 0, "neighbors": { "north_west": [ "field", "microlab" ] } }
+      ],
+```
+The code excerpt above will place the nested chunk "concrete_wall_ew" if the north neighbor is either a field or solid rock, otherwise potentially placing  `"concrete_wall_ns"`; the latter will be placed only if the north_west neighbor is neither a field nor any of the microlab overmaps).
+
 
 ## Mapgen values