joocer · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/docs/blog.css b/docs/blog.css
@@ -172,6 +172,22 @@ article strong {
     color: #fff;
 }
 
+/* Diagrams are PNGs with their own dark card, so they import cleanly into Medium. */
+article figure {
+    margin: 2rem 0;
+}
+article figure img {
+    display: block;
+    width: 100%;
+    height: auto;
+    border-radius: 12px;
+}
+article figcaption {
+    margin-top: 0.6rem;
+    font-size: 0.82rem;
+    color: var(--muted);
+}
+
 /* The one number the piece exists to show. */
 .lede {
     font-size: 1.15rem;

diff --git a/docs/blog/avro-vs-parquet-vs-jsonl.html b/docs/blog/avro-vs-parquet-vs-jsonl.html
diff --git a/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-1-sizes.png b/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-1-sizes.png
diff --git a/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-2-rows-vs-columns.png b/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-2-rows-vs-columns.png
diff --git a/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-3-jsonl.png b/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-3-jsonl.png
diff --git a/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-4-avro.png b/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-4-avro.png
diff --git a/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-5-parquet.png b/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-5-parquet.png
diff --git a/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-6-reading.png b/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-6-reading.png
diff --git a/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-7-pipeline.png b/docs/blog/img/avro-vs-parquet-vs-jsonl/fig-7-pipeline.png
diff --git a/docs/blog/index.html b/docs/blog/index.html
@@ -31,6 +31,20 @@ <h1>Blog</h1>
                     PyArrow, pandas or NumPy. Measurements, not estimates.
                 </p>
 
+                <a class="post-card" href="avro-vs-parquet-vs-jsonl.html">
+                    <h2>
+                        Avro vs Parquet vs JSON Lines: one dataset, three very
+                        different files
+                    </h2>
+                    <p class="post-meta">20 October 2026</p>
+                    <p>
+                        The same 4,630 rows take 1.09 MB as JSON Lines, 113 KB
+                        as Avro and 93 KB as Parquet. Size is the least
+                        interesting difference: what matters is how much of
+                        each file a reader can skip.
+                    </p>
+                </a>
+
                 <a class="post-card" href="performant-python-pipelines-without-the-rust.html">
                     <h2>Performant Python pipelines without the Rust</h2>
                     <p class="post-meta">18 October 2026</p>

diff --git a/medium/avro-vs-parquet-vs-jsonl/table-1.png b/medium/avro-vs-parquet-vs-jsonl/table-1.png
diff --git a/tools/build_format_diagrams.py b/tools/build_format_diagrams.py