Commit `6c1f09c138`

6c1f09c138d40fb92ad968ee4a0ef3d74b56c7da

parent: a5dc89631c

Unsigned

cmc <hello@cleberg.net> · 2026-08-31 23:49 UTC

A list item holds block elements, not just paragraphs (!7)

`#+begin_src` inside a list item rendered as literal prose — visible in the iOS
README view on any repo whose Contributing section puts commands under numbered
steps.

`OrgListItem.content` was `[[OrgObject]]`, paragraphs only, so the parser folded
every non-marker line into the running paragraph. An item's body is now parsed as
a document of its own and held as `[OrgElement]`; the `sublist` field is gone, a
nested list being just a `.list` in the content.

Paragraphs wrap in `<p>` only when the item has more than one, matching orgo;
blocks follow bare. The SwiftUI path renders item content through
`OrgBlockListView`, the same view the document body uses.

Breaking for anyone constructing an `OrgListItem` (only the parser and tests do).

Depends on krz/org-conformance!1 for the `listblocks` case. 89 tests green.

Layout: unified · split

GAPS.md +5 −1

 orgo-compatible mode — `OrgRenderOptions(metadataHeader: false, headingLevelOffset: 1)` —
 so that only real rendering differences remain.
-Of the 12 corpus cases, **11 match orgo exactly** — every case except `outofscope`, which is
+Of the 13 corpus cases, **12 match orgo exactly** — every case except `outofscope`, which is
 `scope: out` in the corpus (deliberately unsupported constructs like `#+INCLUDE`, babel, and
 LaTeX; orgo may also differ there, so it is documentation, not a target). The per-case state
 is recorded in the `expectations` map in `Tests/OrgSwiftTests/ConformanceTests.swift`: a case
   description lists (`term :: definition` → `<dl>`), and multi-paragraph items (an item's
   paragraphs, separated by blank lines, wrap in `<p>`). A latent link-parser bug that let a
   no-description link swallow a later link's `][` was fixed in passing.
+- **`listblocks`** — a list item's body is a block sequence, not a run of paragraphs, so an
+  item holds a source block, an example, a quote, or a table alongside its prose and its
+  sublist, in source order. Paragraphs wrap in `<p>` only when the item has more than one,
+  matching orgo; blocks follow bare.
 - **`tblfm`** — `^` superscript renders (`N^2` → `N<sup>2</sup>`, `x^{group}` supported).
 - **`blocks`** — example blocks are a bare `<pre>`; `#+BEGIN_EXPORT html` passes through
   verbatim while other export backends are dropped; verse renders as `<p class="verse">`

README.md +1

	@@ -17,6 +17,7 @@ parsed once into a document model, and each output format walks it. See
17	Headings (with trailing `:tags:`), paragraphs, ordered/unordered lists (with	17	Headings (with trailing `:tags:`), paragraphs, ordered/unordered lists (with
18	arbitrary-depth nesting, wrapped lines, and `[ ]`/`[x]`/`[-]` task checkboxes),	18	arbitrary-depth nesting, wrapped lines, and `[ ]`/`[x]`/`[-]` task checkboxes),
19	description lists (`term :: definition` → `<dl>`), multi-paragraph list items,	19	description lists (`term :: definition` → `<dl>`), multi-paragraph list items,
		20	list items holding block elements (a source block, table, or quote inside an item),
20	tables (with `:---:` alignment), `#+begin_src` / `example` / `quote` / `center` /	21	tables (with `:---:` alignment), `#+begin_src` / `example` / `quote` / `center` /
21	`verse` / `export` blocks and `#+begin_<name>` special blocks,	22	`verse` / `export` blocks and `#+begin_<name>` special blocks,
22	`#+TITLE`/`#+AUTHOR`/`#+DATE` metadata, `#+CAPTION`/`#+ATTR_HTML`/`#+NAME`	23	`#+TITLE`/`#+AUTHOR`/`#+DATE` metadata, `#+CAPTION`/`#+ATTR_HTML`/`#+NAME`

Sources/OrgSwift/AST/OrgDocument.swift +11 −6

     public var checkbox: OrgCheckbox?
     /// The term of a description-list item (`term :: definition`).
     public var term: [OrgObject]?
-    /// The item's own content: one paragraph normally, several for a multi-paragraph item.
+    /// The item's body, in document order. Usually one paragraph, but an item may hold any
-    public var content: [[OrgObject]]
+    /// block element — a nested list, a source block, a table — so this is a block sequence
-    /// A nested list, when the item has one.
+    /// rather than a list of paragraphs.
-    public var sublist: OrgList?
+    public var content: [OrgElement]
     public init(checkbox: OrgCheckbox? = nil, term: [OrgObject]? = nil,
-                content: [[OrgObject]], sublist: OrgList? = nil) {
+                content: [OrgElement]) {
         self.checkbox = checkbox
         self.term = term
         self.content = content
-        self.sublist = sublist
+    }
+    /// The item's paragraphs, ignoring any other block it carries. Used where only prose is
+    /// meaningful — the `<dd>` of a description list, an item's plain-text reduction.
+    public var paragraphs: [[OrgObject]] {
+        content.compactMap { if case .paragraph(let objects) = $0 { objects } else { nil } }
     }
 }

Sources/OrgSwift/AST/OrgHTMLTreeRenderer.swift +20 −10

                 if let term = item.term {
                     html += "<dt>" + renderInline(term, &notes) + "</dt>\n"
                 }
-                if let first = item.content.first {
+                if !item.content.isEmpty {
-                    html += "<dd>" + renderInline(first, &notes) + "</dd>\n"
+                    html += "<dd>" + renderItemContent(item, &notes) + "</dd>\n"
                 }
             }
             return html + "</dl>\n"
                 case .partial: html += "<code>[-]</code> "
                 }
             }
-            if item.content.count <= 1 {
+            html += renderItemContent(item, &notes)
-                html += renderInline(item.content.first ?? [], &notes)
-            } else {
-                html += item.content.map { "<p>" + renderInline($0, &notes) + "</p>" }.joined(separator: "\n")
-            }
-            if let sublist = item.sublist {
-                html += "\n" + renderList(sublist, &notes)
-            }
             html += "</li>\n"
         }
         return html + "</\(tag)>\n"
     }
+    /// A list item's body. A lone paragraph renders bare inside the `<li>`; two or more get
+    /// their own `<p>`, matching org's exporter. Anything that is not a paragraph — a nested
+    /// list, a source block, a table — renders as the block it is, in source order.
+    private func renderItemContent(_ item: OrgListItem, _ notes: inout OrgFootnotes) -> String {
+        let wrapParagraphs = item.paragraphs.count > 1
+        var parts: [String] = []
+        for child in item.content {
+            if case .paragraph(let objects) = child {
+                let text = renderInline(objects, &notes)
+                parts.append(wrapParagraphs ? "<p>" + text + "</p>" : text)
+            } else {
+                parts.append(element(child, &notes))
+            }
+        }
+        return parts.joined(separator: "\n")
+    }
     private func renderTable(_ table: OrgTable, _ notes: inout OrgFootnotes) -> String {
         var html = "<table>\n"
         var wroteHeader = false

Sources/OrgSwift/AST/OrgParser.swift +12 −39

	@@ -320,49 +320,22 @@ public enum OrgParser {
320	else if head.hasPrefix("[X] ") \|\| head.hasPrefix("[x] ") { checkbox = .on; head = String(head.dropFirst(4)) }	320	else if head.hasPrefix("[X] ") \|\| head.hasPrefix("[x] ") { checkbox = .on; head = String(head.dropFirst(4)) }
321	else if head.hasPrefix("[-] ") { checkbox = .partial; head = String(head.dropFirst(4)) }	321	else if head.hasPrefix("[-] ") { checkbox = .partial; head = String(head.dropFirst(4)) }
322		322
		323	// `term :: definition` splits on the item's first line only, as org requires.
		324	var term: [OrgObject]?
		325	if kind == .description, let range = head.range(of: " :: ") {
		326	term = parseInline(String(head[..<range.lowerBound]))
		327	head = String(head[range.upperBound...])
		328	}
		329
		330	// The item's body is outdented to column 0 and parsed as a document of its own, so an
		331	// item holds whatever a document holds — several paragraphs, a nested list, a source
		332	// block, a table — in source order.
323	let rest = Array(lines.dropFirst())	333	let rest = Array(lines.dropFirst())
324	let childIndent = rest.filter { !$0.trimmingCharacters(in: .whitespaces).isEmpty }	334	let childIndent = rest.filter { !$0.trimmingCharacters(in: .whitespaces).isEmpty }
325	.map(leadingWidth).min() ?? 0	335	.map(leadingWidth).min() ?? 0
326	let outdented = rest.map { dropLeading($0, childIndent) }	336	let body = ([head] + rest.map { dropLeading($0, childIndent) }).joined(separator: "\n")
327
328	var paragraphs: [String] = []
329	var currentParagraph = [head]
330	var sublistLines: [String] = []
331	var inSublist = false
332
333	func flush() {
334	let joined = currentParagraph.joined(separator: " ").trimmingCharacters(in: .whitespaces)
335	if !joined.isEmpty { paragraphs.append(joined) }
336	currentParagraph = []
337	}
338
339	for line in outdented {
340	let trimmed = line.trimmingCharacters(in: .whitespaces)
341	if isListMarkerLine(line) \|\| inSublist {
342	if !inSublist { flush() }
343	inSublist = true
344	sublistLines.append(line)
345	} else if trimmed.isEmpty {
346	flush()
347	} else {
348	currentParagraph.append(trimmed)
349	}
350	}
351	flush()
352
353	var term: [OrgObject]?
354	var content = paragraphs
355	if kind == .description, let first = paragraphs.first, let range = first.range(of: " :: ") {
356	term = parseInline(String(first[..<range.lowerBound]))
357	content[0] = String(first[range.upperBound...])
358	}
359		337
360	return OrgListItem(	338	return OrgListItem(checkbox: checkbox, term: term, content: parse(body).elements)
361	checkbox: checkbox,
362	term: term,
363	content: content.map(parseInline),
364	sublist: sublistLines.isEmpty ? nil : buildList(sublistLines)
365	)
366	}	339	}
367		340
368	// MARK: - Helpers	341	// MARK: - Helpers

Sources/OrgSwiftUI/OrgLayout.swift +3 −2

     struct Item: Identifiable {
         var checkbox: OrgCheckbox?
         var term: AttributedString?
-        var paragraphs: [AttributedString]
+        /// The item's body in source order — usually one paragraph, but an item may hold a
-        var sublist: OrgListLayout?
+        /// nested list, a source block, or a table.
+        var blocks: [OrgBlock]
         var id = UUID()
     }
 }

Sources/OrgSwiftUI/OrgLayoutBuilder.swift +1 −2

                     styled.font = .body.bold()
                     return styled
                 },
-                paragraphs: item.content.map { text($0, &notes) },
+                blocks: item.content.flatMap { block($0, &notes) }
-                sublist: item.sublist.map { listLayout($0, &notes) }
             ))
         }
         return OrgListLayout(kind: list.kind, items: items)

Sources/OrgSwiftUI/OrgListView.swift +13 −25

             Text(marker)
                 .monospacedDigit()
                 .foregroundStyle(.secondary)
-            VStack(alignment: .leading, spacing: 6) {
+            if let checkbox = item.checkbox {
-                if let checkbox = item.checkbox {
+                HStack(alignment: .firstTextBaseline, spacing: 6) {
-                    HStack(alignment: .firstTextBaseline, spacing: 6) {
+                    Image(systemName: Self.symbol(for: checkbox))
-                        Image(systemName: Self.symbol(for: checkbox))
+                        .foregroundStyle(checkbox == .on ? Color.accentColor : .secondary)
-                            .foregroundStyle(checkbox == .on ? Color.accentColor : .secondary)
+                        .accessibilityLabel(Self.label(for: checkbox))
-                            .accessibilityLabel(Self.label(for: checkbox))
+                    body(item)
-                        paragraphs(item)
-                    }
-                } else {
-                    paragraphs(item)
-                }
-                if let sublist = item.sublist {
-                    OrgListView(list: sublist)
                 }
+            } else {
+                body(item)
             }
         }
     }
             if let term = item.term {
                 Text(term).fixedSize(horizontal: false, vertical: true)
             }
-            paragraphs(item).padding(.leading, 16)
+            body(item).padding(.leading, 16)
-            if let sublist = item.sublist {
-                OrgListView(list: sublist).padding(.leading, 16)
-            }
         }
     }
-    private func paragraphs(_ item: OrgListLayout.Item) -> some View {
+    /// The item's blocks, rendered by the same view the document body uses — a nested list,
-        VStack(alignment: .leading, spacing: 6) {
+    /// a source block, and a table all come out looking as they would anywhere else.
-            ForEach(Array(item.paragraphs.enumerated()), id: \.offset) { _, paragraph in
+    private func body(_ item: OrgListLayout.Item) -> some View {
-                Text(paragraph)
+        OrgBlockListView(blocks: item.blocks)
-                    .fixedSize(horizontal: false, vertical: true)
-                    .frame(maxWidth: .infinity, alignment: .leading)
-            }
-        }
     }
     private static func symbol(for checkbox: OrgCheckbox) -> String {

Tests/OrgSwiftTests/ConformanceTests.swift +1

	@@ -56,6 +56,7 @@ private let expectations: [String: Expectation] = [
56	"footnote": .matches,	56	"footnote": .matches,
57	"headings": .matches,	57	"headings": .matches,
58	"images": .matches,	58	"images": .matches,
		59	"listblocks": .matches,
59	"lists": .matches,	60	"lists": .matches,
60	"minimal": .matches,	61	"minimal": .matches,
61	"outofscope": .diverges("out-of-scope constructs; #+INCLUDE and drawers leak — orgo may differ here too"),	62	"outofscope": .diverges("out-of-scope constructs; #+INCLUDE and drawers leak — orgo may differ here too"),

Tests/OrgSwiftTests/OrgRendererTests.swift +31

	@@ -430,6 +430,37 @@ struct OrgRendererTests {
430	#expect(html.contains("<li>a plain sibling</li>"))	430	#expect(html.contains("<li>a plain sibling</li>"))
431	}	431	}
432		432
		433	@Test
		434	func listItemHoldsBlockElements() {
		435	let html = render("""
		436	1. Fork the repository
		437	2. Create a new branch:
		438	#+begin_src bash
		439	git checkout -b my-feature
		440	#+end_src
		441	3. Open a pull request
		442	""")
		443	#expect(html.contains("<li>Fork the repository</li>"))
		444	#expect(html.contains("<li>Create a new branch:\n<pre>"))
		445	#expect(html.contains("git checkout -b my-feature"))
		446	#expect(!html.contains("begin_src"))
		447	}
		448
		449	/// A sublist and a block in the same item keep their source order.
		450	@Test
		451	func listItemKeepsSublistAndBlockInOrder() throws {
		452	let html = render("""
		453	- outer
		454	- inner
		455	#+begin_example
		456	example text
		457	#+end_example
		458	""")
		459	let sublist = try #require(html.range(of: "<li>inner</li>"))
		460	let block = try #require(html.range(of: "example text"))
		461	#expect(sublist.lowerBound < block.lowerBound)
		462	}
		463
433	@Test	464	@Test
434	func exportBlockHtmlPassesThroughLatexDropped() {	465	func exportBlockHtmlPassesThroughLatexDropped() {
435	let html = render("""	466	let html = render("""

Tests/OrgSwiftTests/OrgTreeTests.swift +8 −3

             Issue.record("expected a list"); return
         }
         #expect(list.items.count == 2)
-        let inner = list.items[0].sublist
+        guard case .list(let inner)? = list.items[0].content.last else {
-        #expect(inner != nil)
+            Issue.record("expected a nested list"); return
-        #expect(inner?.items.first?.sublist?.items.count == 1)
+        }
+        #expect(inner.items.count == 1)
+        guard case .list(let deepest)? = inner.items[0].content.last else {
+            Issue.record("expected a twice-nested list"); return
+        }
+        #expect(deepest.items.count == 1)
     }
     @Test

Tests/OrgSwiftUITests/OrgLayoutTests.swift +38 −5

	@@ -23,6 +23,18 @@ struct OrgLayoutTests {
23		23
24	private func plain(_ string: AttributedString) -> String { String(string.characters) }	24	private func plain(_ string: AttributedString) -> String { String(string.characters) }
25		25
		26	/// An item's first paragraph, as plain text.
		27	private func firstParagraph(_ item: OrgListLayout.Item) -> String {
		28	for case .paragraph(let text) in item.blocks { return plain(text) }
		29	return ""
		30	}
		31
		32	/// The nested list an item carries, if any.
		33	private func sublist(_ item: OrgListLayout.Item) -> OrgListLayout? {
		34	for case .list(let list) in item.blocks { return list }
		35	return nil
		36	}
		37
26	@Test	38	@Test
27	func blocksCoverTheElementTree() {	39	func blocksCoverTheElementTree() {
28	let blocks = layout("""	40	let blocks = layout("""
	@@ -90,10 +102,31 @@ struct OrgLayoutTests {
90	Issue.record("expected a list"); return	102	Issue.record("expected a list"); return
91	}	103	}
92	#expect(list.kind == .unordered)	104	#expect(list.kind == .unordered)
93	#expect(plain(list.items[0].paragraphs[0]) == "outer")	105	#expect(firstParagraph(list.items[0]) == "outer")
94	let inner = list.items[0].sublist	106	guard let inner = sublist(list.items[0]) else {
95	#expect(plain(inner?.items[0].paragraphs[0] ?? "") == "inner")	107	Issue.record("expected a nested list"); return
96	#expect(plain(inner?.items[0].sublist?.items[0].paragraphs[0] ?? "") == "deepest")	108	}
		109	#expect(firstParagraph(inner.items[0]) == "inner")
		110	#expect(sublist(inner.items[0]).map { firstParagraph($0.items[0]) } == "deepest")
		111	}
		112
		113	/// The native path renders an item's blocks as blocks; before, a `#+begin_src` inside a
		114	/// list item came out as literal prose.
		115	@Test
		116	func listItemBlocksBecomeBlocks() {
		117	guard case .list(let list) = layout("""
		118	1. Create a new branch:
		119	#+begin_src bash
		120	git checkout -b my-feature
		121	#+end_src
		122	""").blocks.first else {
		123	Issue.record("expected a list"); return
		124	}
		125	#expect(firstParagraph(list.items[0]) == "Create a new branch:")
		126	guard case .code(let code)? = list.items[0].blocks.last else {
		127	Issue.record("expected a code block in the item"); return
		128	}
		129	#expect(plain(code) == "git checkout -b my-feature")
97	}	130	}
98		131
99	@Test	132	@Test
	@@ -108,7 +141,7 @@ struct OrgLayoutTests {
108	}	141	}
109	#expect(described.kind == .description)	142	#expect(described.kind == .description)
110	#expect(plain(described.items[0].term ?? "") == "term")	143	#expect(plain(described.items[0].term ?? "") == "term")
111	#expect(plain(described.items[0].paragraphs[0]) == "definition")	144	#expect(firstParagraph(described.items[0]) == "definition")
112	}	145	}
113		146
114	/// Rule rows are structure, not content: they set the header band and then disappear.	147	/// Rule rows are structure, not content: they set the header band and then disappear.

Commit 6c1f09c138

Commit `6c1f09c138`