diff --git a/README.md b/README.md
new file mode 100644
index 0000000..13d1902
--- /dev/null
+++ b/README.md
@@ -0,0 +1,51 @@
+## Project Structure
+
+- `config.toml`: site config (base_url, title, markdown settings)
+- `content/`: blog posts organized by category (ml-tech, homelab, ai-system, dl4traj)
+- `templates/`: Zola templates + shortcodes
+- `sass/style.scss`: styles with light/dark mode via CSS variables
+- `static/`: favicons, web manifest
+- `public/`: built output
+
+## Shortcodes
+
+Image with max-width constraint. `width` defaults to `500px`:
+
+```md
+{% img(src="./diagram.png", alt="Architecture", width="600px") %}
+```
+
+Figure caption:
+
+```md
+{% cap() %}The *architecture* diagram{% end %}
+```
+
+Block math:
+ 
+```md
+{% math() %}
+\nabla \cdot \mathbf{E} = \frac{\rho}{\epsilon_0}
+{% end %}
+```
+
+Inline math:
+
+```md
+The loss {% m() %}\mathcal{L}{% end %} is minimized.
+```
+
+Inserts table of contents where placed:
+
+```md
+{{ toc() }}
+```
+
+## Cloudflare Pages Deployment
+
+To use a specific version of Zola, and to handle Cloudflare's distinction between preview and production builds:
+
+```bash
+curl -sL https://github.com/getzola/zola/releases/download/v0.22.1/zola-v0.22.1-x86_64-unknown-linux-gnu.tar.gz | tar xz && if [ "$CF_PAGES_BRANCH" = "main" ]; then ./zola build; else ./zola build --base-url $CF_PAGES_URL; fi
+```
+
diff --git a/sass/style.scss b/sass/style.scss
index 93d4872..29f81ea 100644
--- a/sass/style.scss
+++ b/sass/style.scss
@@ -86,7 +86,7 @@ figcaption {
   text-align: center;
   font-size: 0.9rem;
   color: var(--muted);
-  margin-top: 0;
+  margin-top: 1rem;
   margin-bottom: 1.5rem;
 }