Commit `bec396ade8`

bec396ade8d304ad3623576fdc055f9cb4ce1938

parent: 40c9508fc7

Unsigned

cmc <hello@cleberg.net> · 2026-08-31 17:26 UTC

Share footnote numbering and URL resolution across renderers

Both were private to the HTML renderer, so a second renderer in another
module could not reach them. Footnote numbering is output-format agnostic
and moves to OrgFootnotes; the section markup stays HTML-side. Link and
image resolution moves to OrgURLResolver. Both are `package`, so the
public API is unchanged.

Layout: unified · split

Sources/OrgSwift/AST/OrgFootnotes.swift added +57

@@ -0,0 +1,57 @@
	1	import Foundation
	2
	3	/// Assigns footnote numbers in first-reference order and holds the notes they resolve to.
	4	///
	5	/// Numbering is document-wide and order-of-use, so it belongs to the render pass rather than
	6	/// the parse: a renderer walks the tree, calls ``number(for:inline:)`` as it meets each
	7	/// reference, then reads ``notes`` to emit the section. It is output-format agnostic —
	8	/// the HTML renderer and the SwiftUI one share it.
	9	package struct OrgFootnotes {
	10	private var numbers: [String: Int] = [:]
	11	private var order: [String] = []
	12	/// Reference-style definitions, gathered from the document's `[fn:x] …` lines.
	13	private var definitions: [String: [OrgObject]] = [:]
	14	/// Inline definitions, gathered from `[fn:x:text]` references as they are rendered.
	15	private var inlineDefinitions: [String: [OrgObject]] = [:]
	16	package var figureNumber = 0
	17
	18	package init(document: OrgDocument) {
	19	for element in document.elements {
	20	if case .footnoteDefinition(let label, let content) = element {
	21	definitions[label] = content
	22	}
	23	}
	24	}
	25
	26	package mutating func number(for label: String, inline: [OrgObject]? = nil) -> Int {
	27	if let inline, inlineDefinitions[label] == nil { inlineDefinitions[label] = inline }
	28	if let existing = numbers[label] { return existing }
	29	let next = order.count + 1
	30	numbers[label] = next
	31	order.append(label)
	32	return next
	33	}
	34
	35	/// One numbered note, resolved to its content.
	36	package struct Note {
	37	package var number: Int
	38	package var label: String
	39	package var content: [OrgObject]
	40	/// An inline footnote's text sits directly in the item; a reference-style definition
	41	/// is a paragraph, matching org's exporter.
	42	package var isInline: Bool
	43	}
	44
	45	/// The referenced notes, in numbering order. Empty when the document has none, which is
	46	/// the renderer's cue to omit the section entirely.
	47	package var notes: [Note] {
	48	order.map { label in
	49	Note(
	50	number: numbers[label] ?? 0,
	51	label: label,
	52	content: inlineDefinitions[label] ?? definitions[label] ?? [],
	53	isInline: inlineDefinitions[label] != nil
	54	)
	55	}
	56	}
	57	}

Sources/OrgSwift/AST/OrgHTMLTreeRenderer.swift +23 −74

     }
     public func render(_ document: OrgDocument) -> String {
-        var footnotes = FootnoteNumbering(document: document)
+        var footnotes = OrgFootnotes(document: document)
         var html = metadataHeader(document)
         html += document.elements.map { element($0, &footnotes) }.joined()
-        html += footnotes.renderSection(self)
+        html += renderFootnoteSection(&footnotes)
         return html
     }
     // MARK: - URL resolution
-    /// Resolve a link target to a safe `href`, or nil when it cannot be made safe.
+    /// Link and image resolution is shared with the other renderers; see ``OrgURLResolver``.
-    ///
+    private var resolver: OrgURLResolver { OrgURLResolver(options: options) }
-    /// Because the tree keeps targets typed, resolution is a renderer concern applied to the
-    /// `.file` case only — no resolver closure has to be threaded through the parse.
-    private func href(for target: OrgLinkTarget) -> String? {
-        switch target {
-        case .id(let identifier):
-            return sanitizedReadmeLinkURLString("#\(identifier)")
-        case .external(let url):
-            return sanitizedReadmeLinkURLString(url)
-        case .file(let path):
-            return sanitizedReadmeLinkURLString(options.linkURLResolver()?(path) ?? path)
-        }
-    }
-    /// Resolve an image source to a safe `src`, or nil when it cannot be made safe.
-    private func imageSource(_ source: String) -> String? {
-        sanitizedReadmeImageURLString(options.imageURLResolver()?(source) ?? source)
-    }
     // MARK: - Blocks
-    private func element(_ element: OrgElement, _ notes: inout FootnoteNumbering) -> String {
+    private func element(_ element: OrgElement, _ notes: inout OrgFootnotes) -> String {
         switch element {
         case .heading(let heading):
             let level = min(6, max(1, heading.level + options.headingLevelOffset))
         }
     }
-    private func renderList(_ list: OrgList, _ notes: inout FootnoteNumbering) -> String {
+    private func renderList(_ list: OrgList, _ notes: inout OrgFootnotes) -> String {
         if list.kind == .description {
             var html = "<dl>\n"
             for item in list.items {
         return html + "</\(tag)>\n"
     }
-    private func renderTable(_ table: OrgTable, _ notes: inout FootnoteNumbering) -> String {
+    private func renderTable(_ table: OrgTable, _ notes: inout OrgFootnotes) -> String {
         var html = "<table>\n"
         var wroteHeader = false
         var inBody = false
     /// The `<img>` for a figure, or nil when the source cannot be resolved to a safe URL —
     /// in which case the caller falls back to text rather than pointing at something unsafe.
     private func imageTag(_ figure: OrgFigure, caption: [OrgObject]?) -> String? {
-        guard let source = imageSource(figure.source) else { return nil }
+        guard let source = resolver.imageSource(figure.source) else { return nil }
         let alt = figure.alt ?? caption.map { plainText($0) } ?? ""
         var html = #"<img src="\#(source)" alt="\#(escapeHTMLAttribute(alt))""#
         for (key, value) in figure.attributes where key != "alt" {
     // MARK: - Inline
-    func renderInline(_ objects: [OrgObject], _ notes: inout FootnoteNumbering) -> String {
+    func renderInline(_ objects: [OrgObject], _ notes: inout OrgFootnotes) -> String {
         var html = ""
         for object in objects {
             switch object {
                 html += ##"<sup class="footnote-ref"><a id="fnr-\##(number)" href="#fn-\##(number)">\##(number)</a></sup>"##
             case .link(let link):
                 let text = link.description.map { renderInline($0, &notes) }
-                    ?? escapeHTML(displayValue(link.target))
+                    ?? escapeHTML(resolver.displayValue(link.target))
                 // An unsafe or unresolvable target degrades to its text, never a bad anchor.
-                if let href = href(for: link.target) {
+                if let href = resolver.href(for: link.target) {
                     html += #"<a href="\#(href)">\#(text)</a>"#
                 } else {
                     html += text
         return html
     }
-    private func displayValue(_ target: OrgLinkTarget) -> String {
-        switch target {
-        case .external(let url): return url
-        case .file(let path): return path
-        case .id(let identifier): return identifier
-        }
-    }
     /// Inline objects reduced to plain text, for an `alt` attribute.
     func plainText(_ objects: [OrgObject]) -> String {
         objects.map { object in
             case .verbatim(let text), .code(let text): return text
             case .bold(let c), .italic(let c), .underline(let c), .strikeThrough(let c), .superscript(let c):
                 return plainText(c)
-            case .link(let link): return link.description.map { plainText($0) } ?? displayValue(link.target)
+            case .link(let link): return link.description.map { plainText($0) } ?? resolver.displayValue(link.target)
             case .timestamp(let stamp): return stamp.displayValue
             case .image(let figure): return figure.alt ?? ""
             case .footnoteRef, .lineBreak: return ""
     }
 }
-// MARK: - Footnote numbering
+// MARK: - Footnote section
-/// Assigns footnote numbers in first-reference order and renders the notes section.
-struct FootnoteNumbering {
-    private var numbers: [String: Int] = [:]
-    private var order: [String] = []
-    /// Reference-style definitions, gathered from the document's `[fn:x] …` lines.
-    private var definitions: [String: [OrgObject]] = [:]
-    /// Inline definitions, gathered from `[fn:x:text]` references as they are rendered.
-    private var inlineDefinitions: [String: [OrgObject]] = [:]
-    var figureNumber = 0
-    init(document: OrgDocument) {
-        for element in document.elements {
-            if case .footnoteDefinition(let label, let content) = element {
-                definitions[label] = content
-            }
-        }
-    }
-    mutating func number(for label: String, inline: [OrgObject]? = nil) -> Int {
-        if let inline, inlineDefinitions[label] == nil { inlineDefinitions[label] = inline }
-        if let existing = numbers[label] { return existing }
-        let next = order.count + 1
-        numbers[label] = next
-        order.append(label)
-        return next
-    }
-    mutating func renderSection(_ renderer: OrgHTMLTreeRenderer) -> String {
+private extension OrgHTMLTreeRenderer {
-        guard !order.isEmpty else { return "" }
+    /// The `<section class="footnotes">` org's exporter puts at the end of a document.
+    func renderFootnoteSection(_ notes: inout OrgFootnotes) -> String {
+        let collected = notes.notes
+        guard !collected.isEmpty else { return "" }
         var html = "<section class=\"footnotes\" aria-label=\"Footnotes\">\n<hr>\n<ol>\n"
-        for label in order {
+        for note in collected {
-            let n = numbers[label] ?? 0
+            let n = note.number
             let back = ##"<a class="footnote-back" href="#fnr-\##(n)" aria-label="Back to reference \##(n)">&#8617;</a>"##
-            // An inline footnote's text sits directly in the item; a reference-style
+            let body = renderInline(note.content, &notes)
-            // definition is a paragraph, matching org's exporter.
+            if note.isInline {
-            if let inline = inlineDefinitions[label] {
+                html += "<li id=\"fn-\(n)\">\(body) \(back)</li>\n"
-                html += "<li id=\"fn-\(n)\">\(renderer.renderInline(inline, &self)) \(back)</li>\n"
             } else {
-                let body = definitions[label].map { renderer.renderInline($0, &self) } ?? ""
                 html += "<li id=\"fn-\(n)\"><p>\(body)</p>\n \(back)</li>\n"
             }
         }

Sources/OrgSwift/AST/OrgURLResolver.swift added +40

@@ -0,0 +1,40 @@
	1	import Foundation
	2
	3	/// Resolves a link target or image source to a safe absolute URL string, or nil when it
	4	/// cannot be made safe.
	5	///
	6	/// Because the tree keeps targets typed, resolution is a renderer concern applied to the
	7	/// `.file` case only — no resolver closure has to be threaded through the parse. Both
	8	/// renderers resolve identically, so a link that degrades to text in HTML degrades to text
	9	/// natively too.
	10	package struct OrgURLResolver: Sendable {
	11	package var options: OrgRenderOptions
	12
	13	package init(options: OrgRenderOptions) {
	14	self.options = options
	15	}
	16
	17	package func href(for target: OrgLinkTarget) -> String? {
	18	switch target {
	19	case .id(let identifier):
	20	return sanitizedReadmeLinkURLString("#\(identifier)")
	21	case .external(let url):
	22	return sanitizedReadmeLinkURLString(url)
	23	case .file(let path):
	24	return sanitizedReadmeLinkURLString(options.linkURLResolver()?(path) ?? path)
	25	}
	26	}
	27
	28	package func imageSource(_ source: String) -> String? {
	29	sanitizedReadmeImageURLString(options.imageURLResolver()?(source) ?? source)
	30	}
	31
	32	/// The text a target shows when it carries no description.
	33	package func displayValue(_ target: OrgLinkTarget) -> String {
	34	switch target {
	35	case .external(let url): return url
	36	case .file(let path): return path
	37	case .id(let identifier): return identifier
	38	}
	39	}
	40	}

Commit bec396ade8

Commit `bec396ade8`