From 8f58401629c24f338a6453eaff83288c728d927e Mon Sep 17 00:00:00 2001
From: mscherer <dereuromark@web.de>
Date: Wed, 20 May 2026 02:38:39 +0200
Subject: [PATCH] docs: add Attachment Model overview

Documents the governing principle ("attributes precede their target;
adjacency selects the tighter target where supported") and a single
table covering all djot-php attribute targets (block, inline, <li>,
<dt>, <dd>, <dl>, table row, table cell, marker-glyph not-addressable
note). Notes the start/type/reversed strip on <li>/<dd> (#187) and
the list-item last-content-line rule (#186).
---
 docs/guide/syntax.md           |  5 +++++
 docs/reference/enhancements.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/docs/guide/syntax.md b/docs/guide/syntax.md
index a83ef5c0..9d192f84 100644
--- a/docs/guide/syntax.md
+++ b/docs/guide/syntax.md
@@ -1161,6 +1161,11 @@ And so are you.</p>
 
 ### Block Attributes
 
+For an overview of where attributes attach for each block construct
+(lists, definition lists, tables, etc.), see
+[Attachment Model](/reference/enhancements#attachment-model) in the
+reference.
+
 Apply attributes to the following block using `{...}` syntax.
 
 **Input:**
diff --git a/docs/reference/enhancements.md b/docs/reference/enhancements.md
index 24c301f2..d479e52b 100644
--- a/docs/reference/enhancements.md
+++ b/docs/reference/enhancements.md
@@ -361,6 +361,34 @@ They said:
 
 These are djot syntax features we've implemented that aren't yet in the upstream spec.
 
+### Attachment Model
+
+This summarises where djot-php expects an attribute block (`{...}`)
+relative to its target. The governing principle is djot's own:
+**attributes precede their target; adjacency selects the tighter
+target where supported.** Two constructs (list items, `<dd>`) extend
+this with a deliberate exception for the *last content line* of the
+container.
+
+| Target | Attribute position | Notes |
+|--------|--------------------|-------|
+| Any block (list as a whole, table, fenced div, paragraph, etc.) | `{...}` on the **preceding** line | Standard djot. Applied to the next block. |
+| Inline span | `text{...}` **adjacent** (no space) | Standard djot. Adjacency selects the tightest target. |
+| List item `<li>` | `{...}` as the **last content line of the item**, at content indent | djot-php extension. If another block follows the `{...}` in the same item, `{...}` reverts to a preceding block-attribute for that following block. |
+| `<dt>` (term) | `{...}` on the **line after** the term, at content indent | djot-php extension. |
+| `<dd>` (definition) | `{...}` as the **last line** of the definition block | djot-php extension. Mirror of the list-item rule. |
+| `<dl>` (list as a whole) | `{...}` on the **preceding** line, before the first term | djot-php extension. |
+| Table row | `\| cell \|{...}` after the **final** pipe | djot-php extension. |
+| Table cell | `\|{...} content \|` after the **opening** pipe | djot-php extension. |
+| List **marker glyph** (the bullet / number) | — not addressable — | There is no AST node for the marker. Style the parent `<li>` (or the list) and target the marker via CSS `::marker`. |
+
+**Stripped names:** `start`, `type`, and `reversed` are HTML
+attributes valid only on `<ol>`. djot-php silently drops them from
+`<li>` / `<dd>` output to keep the HTML valid; use a preceding
+block-attribute line on the list itself to set them on `<ol>`.
+
+---
+
 ### Task List Underscore Notation
 
 **Related:** [jgm/djot#305](https://github.com/jgm/djot/issues/305)