Rearrange filter reference docs

Author: jg-rp

docs/filter_reference.md

@@ -514,17 +514,17 @@ Escape special characters in a string for safe use in HTML.
 
 This filter replaces the characters `&`, `<`, `>`, `'`, and `"` with their corresponding HTML-safe sequences:
 
-    - `&` -> `&amp;`
-    - `<` -> `&lt;`
-    - `>` -> `&gt;`
-    - `'` -> `&#39;`
-    - `"` -> `&#34;`
+- `&` -> `&amp;`
+- `<` -> `&lt;`
+- `>` -> `&gt;`
+- `'` -> `&#39;`
+- `"` -> `&#34;`
 
 This helps prevent HTML injection (XSS) when rendering untrusted content in HTML element bodies or attributes.
 
-TODO: important
+!!! warning
 
-Important: This filter does **not** make strings safe for use in JavaScript, including in `<script>` blocks, inline event handler attributes (e.g. `onerror`), or other JavaScript contexts. For those cases, use the `escapejs` filter instead.
+    This filter does **not** make strings safe for use in JavaScript, including in `<script>` blocks, inline event handler attributes (e.g. `onerror`), or other JavaScript contexts. For those cases, use the [`escapejs`](#escapejs) filter instead.
 
 ```liquid2
 {{ "Have you read 'James & the Giant Peach'?" | escape }}
@@ -536,19 +536,31 @@ Have you read &#39;James &amp; the Giant Peach&#39;?
 
 ## escapejs
 
+```
+<string> | escapejs
+```
+
 Escape characters for safe use in JavaScript string literals.
 
 This filter escapes a string for embedding inside **JavaScript string literals**, using either single or double quotes (e.g. `'...'` or `"..."`). It replaces control characters and potentially dangerous symbols with their corresponding Unicode escape sequences.
 
-TODO: important
+Escaped characters include:
+
+- ASCII control characters (U+0000 to U+001F)
+- Characters like quotes, angle brackets, ampersands, equals signs - Line/paragraph separators (U+2028, U+2029)
+
+!!! warning
+
+    This filter does **not** make strings safe for use in JavaScript template literals (backtick strings), or in raw JavaScript expressions. Use it only when placing data inside quoted JS strings within inline `<script>` blocks or event handlers.
 
-**Important:** This filter does **not** make strings safe for use in JavaScript template literals (backtick strings), or in raw JavaScript expressions. Use it only when placing data inside quoted JS strings within inline `<script>` blocks or event handlers.
+    TODO: point to JSON filter
 
-TODO: point to JSON filter
+    **Recommended alternatives:**
 
-**Recommended alternatives:** - Pass data using HTML `data-*` attributes and read them in JS via `element.dataset`. - For structured data, prefer a JSON-serialization approach....
+    - Pass data using HTML `data-*` attributes and read them in JS via `element.dataset`.
+    - For structured data, prefer a JSON-serialization approach....
 
-Escaped characters include: - ASCII control characters (U+0000 to U+001F) - Characters like quotes, angle brackets, ampersands, equals signs - Line/paragraph separators (U+2028, U+2029)
+TODO: example
 
 ## escape_once