joocer · Oct 21, 2026 · Oct 21, 2026
diff --git a/docs/blog/img/understanding-avro/fig-1-record.png b/docs/blog/img/understanding-avro/fig-1-record.png
diff --git a/docs/blog/img/understanding-avro/fig-2-varint.png b/docs/blog/img/understanding-avro/fig-2-varint.png
diff --git a/docs/blog/img/understanding-avro/fig-3-file.png b/docs/blog/img/understanding-avro/fig-3-file.png
diff --git a/docs/blog/img/understanding-avro/fig-4-codecs.png b/docs/blog/img/understanding-avro/fig-4-codecs.png
diff --git a/docs/blog/img/understanding-avro/fig-5-split.png b/docs/blog/img/understanding-avro/fig-5-split.png
diff --git a/docs/blog/img/understanding-avro/fig-6-evolution.png b/docs/blog/img/understanding-avro/fig-6-evolution.png
diff --git a/docs/blog/img/understanding-avro/fig-7-walk.png b/docs/blog/img/understanding-avro/fig-7-walk.png
diff --git a/docs/blog/index.html b/docs/blog/index.html
@@ -31,6 +31,17 @@ <h1>Blog</h1>
                     PyArrow, pandas or NumPy. Measurements, not estimates.
                 </p>
 
+                <a class="post-card" href="understanding-avro.html">
+                    <h2>Understanding Avro: the file format built for moving data</h2>
+                    <p class="post-meta">21 October 2026</p>
+                    <p>
+                        One launch record takes 234 bytes as JSON and 96 as
+                        Avro, with no field names in sight. What's inside an
+                        Avro file: the schema, the byte encoding, blocks and
+                        sync markers, codecs, and how a schema can change
+                        without breaking old data.
+                    </p>
+                </a>
                 <a class="post-card" href="avro-vs-parquet-vs-jsonl.html">
                     <h2>
                         Avro vs Parquet vs JSON Lines: one dataset, three very

diff --git a/docs/blog/understanding-avro.html b/docs/blog/understanding-avro.html
diff --git a/tools/build_avro_diagrams.py b/tools/build_avro_diagrams.py