From 7343b769a676769d4aa34ef5c02f1567f21fff18 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Wed, 25 Feb 2026 13:32:06 -0500
Subject: [PATCH] nicer formatting

---
 .../docs/07-misc/01-best-practices.md         | 21 +++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/documentation/docs/07-misc/01-best-practices.md b/documentation/docs/07-misc/01-best-practices.md
index 625766a8a9..50cb0a8131 100644
--- a/documentation/docs/07-misc/01-best-practices.md
+++ b/documentation/docs/07-misc/01-best-practices.md
@@ -67,9 +67,26 @@ let color = type === 'danger' ? 'red' : 'green';
 
 ## Events
 
-Any element attribute starting with `on` is treated as an event listener (e.g. `<button onclick={() => {...}}>`). Beyond that, they are regular attributes which means they work with shorthand (`<button {onclick}>`), spread (`<button {...props}>`) and so on.
+Any element attribute starting with `on` is treated as an event listener:
 
-If you need to attach listeners to `window` or `document` you can use `<svelte:window onclick={...}>` or `<svelte:document onclick={...}>`. Avoid using `onMount` or `$effect` for this.
+```svelte
+<button onclick={() => {...}}>click me</button>
+
+<!-- attribute shorthand also works -->
+<button {onclick}>...</button>
+
+<!-- so do spread attributes -->
+<button {...props}>...</button>
+```
+
+If you need to attach listeners to `window` or `document` you can use `<svelte:window>` and `<svelte:document>`:
+
+```svelte
+<svelte:window onkeydown={...} />
+<svelte:document onvisibilitychange={...} />
+```
+
+Avoid using `onMount` or `$effect` for this.
 
 ## Each blocks