diff --git a/docs/img/library-layout.dot b/docs/img/library-layout.dot
new file mode 100644
index 00000000000..9afa87b93c5
--- /dev/null
+++ b/docs/img/library-layout.dot
@@ -0,0 +1,39 @@
+// See: https://www.graphviz.org/documentation/
+digraph {
+  // This generates library-layout.png using the following command:
+  // dot -Tsvg -olibrary-layout.svg library-layout.dot
+  graph [
+    splines=line
+  ]
+  node [
+    shape=box
+  ]
+
+  subgraph {
+    // This subgraph provides the labels on left margin
+    node [
+      margin="0.0,0.0"
+      shape=none
+      width=0.0
+    ]
+    "Metadata:" -> "Format:" -> "Structure:" -> "Layout:" [style=invis]
+  }
+
+  subgraph cluster1 {
+    peripheries=0
+    "library.properties" [height=1.0 margin="0.0,0.0" shape=diamond width=0.0]
+    "library.properties" -> "1.5" [label="yes"]
+    "library.properties" -> "1.0" [label="no"]
+    subgraph cluster2 {
+      peripheries=0
+      rank=same
+      "1.5"
+      "1.0"
+    }
+    "1.5" -> "src/"
+    "src/" [shape=diamond]
+    "src/" -> "recursive" [label=" yes"]
+    "src/" -> "flat" [label="no"]
+    "1.0" -> "flat"
+  }
+}
diff --git a/docs/img/library-layout.svg b/docs/img/library-layout.svg
new file mode 100644
index 00000000000..dc1f7bf72a7
--- /dev/null
+++ b/docs/img/library-layout.svg
@@ -0,0 +1,117 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 2.49.0 (20210828.1703)
+ -->
+<!-- Pages: 1 -->
+<svg width="239pt" height="359pt"
+ viewBox="0.00 0.00 238.50 359.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 355)">
+<polygon fill="white" stroke="transparent" points="-4,4 -4,-355 234.5,-355 234.5,4 -4,4"/>
+<g id="clust2" class="cluster">
+<title>cluster1</title>
+</g>
+<g id="clust3" class="cluster">
+<title>cluster2</title>
+</g>
+<!-- Metadata: -->
+<g id="node1" class="node">
+<title>Metadata:</title>
+<text text-anchor="middle" x="27.5" y="-295.3" font-family="Times New Roman,serif" font-size="14.00">Metadata:</text>
+</g>
+<!-- Format: -->
+<g id="node2" class="node">
+<title>Format:</title>
+<text text-anchor="middle" x="27.5" y="-190.3" font-family="Times New Roman,serif" font-size="14.00">Format:</text>
+</g>
+<!-- Metadata:&#45;&gt;Format: -->
+<!-- Structure: -->
+<g id="node3" class="node">
+<title>Structure:</title>
+<text text-anchor="middle" x="27.5" y="-117.3" font-family="Times New Roman,serif" font-size="14.00">Structure:</text>
+</g>
+<!-- Format:&#45;&gt;Structure: -->
+<!-- Layout: -->
+<g id="node4" class="node">
+<title>Layout:</title>
+<text text-anchor="middle" x="27.5" y="-30.3" font-family="Times New Roman,serif" font-size="14.00">Layout:</text>
+</g>
+<!-- Structure:&#45;&gt;Layout: -->
+<!-- library.properties -->
+<g id="node5" class="node">
+<title>library.properties</title>
+<polygon fill="none" stroke="black" points="144.5,-335 75.19,-299 144.5,-263 213.81,-299 144.5,-335"/>
+<text text-anchor="middle" x="144.5" y="-295.3" font-family="Times New Roman,serif" font-size="14.00">library.properties</text>
+</g>
+<!-- 1.5 -->
+<g id="node6" class="node">
+<title>1.5</title>
+<polygon fill="none" stroke="black" points="134.5,-212 80.5,-212 80.5,-176 134.5,-176 134.5,-212"/>
+<text text-anchor="middle" x="107.5" y="-190.3" font-family="Times New Roman,serif" font-size="14.00">1.5</text>
+</g>
+<!-- library.properties&#45;&gt;1.5 -->
+<g id="edge4" class="edge">
+<title>library.properties&#45;&gt;1.5</title>
+<path fill="none" stroke="black" d="M133.9,-268.48C128.64,-253.85 122.33,-236.29 117.2,-222.01"/>
+<polygon fill="black" stroke="black" points="120.38,-220.51 113.71,-212.28 113.79,-222.88 120.38,-220.51"/>
+<text text-anchor="middle" x="134" y="-233.8" font-family="Times New Roman,serif" font-size="14.00">yes</text>
+</g>
+<!-- 1.0 -->
+<g id="node7" class="node">
+<title>1.0</title>
+<polygon fill="none" stroke="black" points="206.5,-212 152.5,-212 152.5,-176 206.5,-176 206.5,-212"/>
+<text text-anchor="middle" x="179.5" y="-190.3" font-family="Times New Roman,serif" font-size="14.00">1.0</text>
+</g>
+<!-- library.properties&#45;&gt;1.0 -->
+<g id="edge5" class="edge">
+<title>library.properties&#45;&gt;1.0</title>
+<path fill="none" stroke="black" d="M154.62,-268.21C159.59,-253.58 165.54,-236.09 170.37,-221.87"/>
+<polygon fill="black" stroke="black" points="173.76,-222.78 173.66,-212.19 167.13,-220.53 173.76,-222.78"/>
+<text text-anchor="middle" x="174" y="-233.8" font-family="Times New Roman,serif" font-size="14.00">no</text>
+</g>
+<!-- src/ -->
+<g id="node8" class="node">
+<title>src/</title>
+<polygon fill="none" stroke="black" points="107.5,-139 72.64,-121 107.5,-103 142.36,-121 107.5,-139"/>
+<text text-anchor="middle" x="107.5" y="-117.3" font-family="Times New Roman,serif" font-size="14.00">src/</text>
+</g>
+<!-- 1.5&#45;&gt;src/ -->
+<g id="edge6" class="edge">
+<title>1.5&#45;&gt;src/</title>
+<path fill="none" stroke="black" d="M107.5,-175.81C107.5,-167.79 107.5,-158.05 107.5,-149.07"/>
+<polygon fill="black" stroke="black" points="111,-149.03 107.5,-139.03 104,-149.03 111,-149.03"/>
+</g>
+<!-- flat -->
+<g id="node10" class="node">
+<title>flat</title>
+<polygon fill="none" stroke="black" points="212.5,-52 158.5,-52 158.5,-16 212.5,-16 212.5,-52"/>
+<text text-anchor="middle" x="185.5" y="-30.3" font-family="Times New Roman,serif" font-size="14.00">flat</text>
+</g>
+<!-- 1.0&#45;&gt;flat -->
+<g id="edge9" class="edge">
+<title>1.0&#45;&gt;flat</title>
+<path fill="none" stroke="black" d="M180.18,-175.96C181.21,-148.35 183.2,-95.37 184.43,-62.53"/>
+<polygon fill="black" stroke="black" points="187.94,-62.35 184.82,-52.22 180.94,-62.08 187.94,-62.35"/>
+</g>
+<!-- recursive -->
+<g id="node9" class="node">
+<title>recursive</title>
+<polygon fill="none" stroke="black" points="140,-52 73,-52 73,-16 140,-16 140,-52"/>
+<text text-anchor="middle" x="106.5" y="-30.3" font-family="Times New Roman,serif" font-size="14.00">recursive</text>
+</g>
+<!-- src/&#45;&gt;recursive -->
+<g id="edge7" class="edge">
+<title>src/&#45;&gt;recursive</title>
+<path fill="none" stroke="black" d="M107.3,-102.8C107.16,-91.16 106.98,-75.55 106.82,-62.24"/>
+<polygon fill="black" stroke="black" points="110.32,-62.13 106.7,-52.18 103.32,-62.22 110.32,-62.13"/>
+<text text-anchor="middle" x="118" y="-73.8" font-family="Times New Roman,serif" font-size="14.00"> yes</text>
+</g>
+<!-- src/&#45;&gt;flat -->
+<g id="edge8" class="edge">
+<title>src/&#45;&gt;flat</title>
+<path fill="none" stroke="black" d="M118.35,-108.18C129.79,-95.71 148.14,-75.71 162.78,-59.76"/>
+<polygon fill="black" stroke="black" points="165.43,-62.04 169.62,-52.31 160.28,-57.31 165.43,-62.04"/>
+<text text-anchor="middle" x="158" y="-73.8" font-family="Times New Roman,serif" font-size="14.00">no</text>
+</g>
+</g>
+</svg>
diff --git a/docs/library-specification.md b/docs/library-specification.md
index f8492e6e42c..232f67829aa 100644
--- a/docs/library-specification.md
+++ b/docs/library-specification.md
@@ -163,6 +163,15 @@ only needs to run on Arduino IDE 1.5.x+, we recommend placing all source code in
 recursive compilation of nested source folders, its code must be in the src/ folder (since Arduino IDE 1.0.x doesn’t
 support recursive compilation, backwards compatibility wouldn’t be possible anyway).
 
+##### Library layout
+
+![Library layout](img/library-layout.svg)
+
+| Layout        | root compiled | `src` compiled | `utility` compiled |
+| ------------- | ------------- | -------------- | ------------------ |
+| **recursive** | no            | recursively    | no                 |
+| **flat**      | yes           | no             | yes                |
+
 #### Precompiled binaries
 
 The `precompiled` field of [library.properties](#libraryproperties-file-format) enables support for the use of