Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocFormats/MarkdownExporter.swift3// Description: Markdown export (pandoc-flavoured CommonMark + GFM tables): front matter, headings, lists, quotes, code, tables,4// footnotes, math, citations, images. What Markdown cannot express is reported, never dropped silently.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel10import DocContainer1112public enum MarkdownExporter {13 public static func export(_ doc: DocumentModel, options: ExportOptions = ExportOptions()) -> ExportResult {14 var writer = MarkdownWriter(doc, options: options)15 let text = writer.write()16 return ExportResult(data: Data(text.utf8), warnings: writer.ctx.finalWarnings(source: doc, format: .markdown))17 }18}1920struct MarkdownWriter {21 var ctx: ExportContext22 private var doc: DocumentModel { ctx.doc }23 private var slugs: [String: String] = [:]24 private var noteLabels: [String: String] = [:]2526 private enum Sty: Equatable { case link(String), bold, italic, strike, underline, sub, sup, mark }27 private struct Piece { var text: String; var styles: [Sty]; var isSpace = false; var isBreak = false }2829 init(_ source: DocumentModel, options: ExportOptions) {30 ctx = ExportContext(source, options: options)31 var slugger = Slugger()32 for block in doc.body {33 guard case .paragraph(let p) = block, p.style == StyleID.title || ModelIdiom.headingLevel(p, styles: doc.styles) != nil else { continue }34 // Same sequence as the importer (and pandoc): every heading takes a slug, an explicit anchor then replaces it.35 slugs[p.id] = slugger.unique(ctx.headingNumberPrefix(p) + p.visibleText)36 if let name = MarkdownWriter.anchorName(p) { slugs[p.id] = name }37 }38 for (ref, _) in ctx.orderedNotes { noteLabels[ref.id] = (ref.kind == .footnote ? "" : "en") + String(ctx.numbering.noteNumbers[ref.id] ?? 0) }39 }4041 /// The name of a leading bookmark that can be written as a heading attribute ({#name}).42 private static func anchorName(_ p: Paragraph) -> String? {43 guard case .bookmark(let name)? = p.runs.first?.inline, !name.isEmpty, name.allSatisfy({ $0.isLetter || $0.isNumber || "-_.:".contains($0) }) else { return nil }44 return name45 }4647 // MARK: Escaping4849 private static func escape(_ s: String, lineStart: Bool, braces: Bool = false) -> String {50 var out = ""51 let scalars = Array(s.unicodeScalars)52 var k = 053 if lineStart {54 // Constructs that only mean something at the start of a line.55 var digits = 056 while digits < scalars.count, scalars[digits].value >= 48, scalars[digits].value <= 57 { digits += 1 }57 if digits > 0, digits < scalars.count, digits <= 9, scalars[digits] == "." || scalars[digits] == ")" {58 out += String(String.UnicodeScalarView(scalars[..<digits])) + "\\" + String(scalars[digits])59 k = digits + 160 } else if let f = scalars.first, "#+-=:%".unicodeScalars.contains(f) {61 out += "\\" + String(f)62 k = 163 }64 }65 while k < scalars.count {66 let u = scalars[k]67 switch u {68 case "\\", "`", "*", "_", "[", "]", "<", ">", "$", "~", "^", "|": out += "\\"; out.unicodeScalars.append(u)69 case "{", "}":70 if braces { out += "\\" }71 out.unicodeScalars.append(u)72 case "&":73 let next = k + 1 < scalars.count ? scalars[k + 1] : " "74 out += next == "#" || (next.isASCII && next.properties.isAlphabetic) ? "\\&" : "&"75 case "@":76 let previous = k > 0 ? scalars[k - 1] : " "77 out += previous.properties.isAlphabetic || (previous.value >= 48 && previous.value <= 57) ? "@" : "\\@"78 case ":":79 // Text that merely looks like a URL must not come back as a link (GFM autolinks).80 if k + 2 < scalars.count, scalars[k + 1] == "/", scalars[k + 2] == "/" { out += ":\\/\\/"; k += 2 } else { out += ":" }81 case ".":82 let isWWW = k >= 3 && String(String.UnicodeScalarView(scalars[(k - 3)..<k])).lowercased() == "www" && (k == 3 || !scalars[k - 4].properties.isAlphabetic)83 out += isWWW ? "\\." : "."84 default: out.unicodeScalars.append(u)85 }86 k += 187 }88 return out89 }9091 private static func codeSpan(_ text: String) -> String {92 var longest = 0, current = 093 for ch in text { if ch == "`" { current += 1; longest = max(longest, current) } else { current = 0 } }94 let fence = String(repeating: "`", count: longest + 1)95 let pad = text.hasPrefix("`") || text.hasSuffix("`") || (text.hasPrefix(" ") && text.hasSuffix(" ") && text.contains { $0 != " " }) ? " " : ""96 return fence + pad + text + pad + fence97 }9899 private static func destination(_ url: String) -> String {100 url.contains(where: { $0 == " " || $0 == "(" || $0 == ")" || $0 == "<" || $0 == ">" }) ? "<" + url.replacingOccurrences(of: "<", with: "%3C").replacingOccurrences(of: ">", with: "%3E") + ">" : url101 }102103 // MARK: Inline content104105 private enum LineBreakMode { case hard, html, space }106107 private mutating func inline(_ p: Paragraph, breaks: LineBreakMode = .hard, braces: Bool = false, skipLeadingBookmark: Bool = false) -> String {108 var pieces: [Piece] = []109 var sequenceIndex = 0110 var atLineStart = true111 func object(_ text: String) { if !text.isEmpty { pieces.append(Piece(text: text, styles: [])); atLineStart = false } }112 for (index, run) in p.runs.enumerated() {113 if let inline = run.inline {114 switch inline {115 case .image(let image):116 guard let asset = doc.assets[image.asset] else {117 ctx.warnings.add(.dropped, "Missing images", "An image has no data in the document; its alternative text was written instead.")118 object(MarkdownWriter.escape(image.altText, lineStart: atLineStart))119 break120 }121 let alt = MarkdownWriter.escape(image.altText.replacingOccurrences(of: lineSeparatorCharacter, with: " "), lineStart: false)122 object(" ?? ImageSupport.dataURI(asset)))")123 case .shape(let shape): object(MarkdownWriter.escape(shape.text.isEmpty ? shape.altText : shape.text, lineStart: atLineStart))124 case .equation(let e): object(e.display ? "$$\(e.latex)$$" : "$\(e.latex)$")125 case .note(let ref): object(noteLabels[ref.id].map { "[^\($0)]" } ?? "")126 case .citation(let c):127 object(ctx.options.citations == nil ? ctx.citationText(c) : MarkdownWriter.escape(ctx.citationText(c), lineStart: atLineStart))128 case .crossRef(let ref):129 let text = MarkdownWriter.escape(ctx.crossRefText(ref), lineStart: atLineStart)130 if let target = ctx.crossRefTarget(ref), let slug = slugs[target] { object("[\(text)](#\(slug))") } else { object(text) }131 case .field(let f): object(MarkdownWriter.escape(ctx.fieldText(f, in: p, sequenceIndex: &sequenceIndex), lineStart: atLineStart))132 case .bookmark(let name):133 if !(skipLeadingBookmark && index == 0) { object("<a id=\"\(HTMLEntities.escapeAttribute(name))\"></a>") }134 }135 continue136 }137 let c = ModelIdiom.explicitChar(run, styles: doc.styles)138 var styles: [Sty] = []139 if let link = c.link, !link.isEmpty { styles.append(.link(link)) }140 if ModelIdiom.isBold(c) { styles.append(.bold) }141 if c.italic == true { styles.append(.italic) }142 if c.strikethrough == true { styles.append(.strike) }143 if c.underline == true, c.link == nil { styles.append(.underline) }144 if c.vertical == .subscript { styles.append(.sub) }145 if c.vertical == .superscript { styles.append(.sup) }146 if c.highlight != nil { styles.append(.mark) }147 let isCode = run.charStyle == StyleID.inlineCode148 // Split the run into words, white space and line breaks so emphasis markers always touch a word.149 var current = ""150 var currentIsSpace = false151 func flushCurrent() {152 guard !current.isEmpty else { return }153 if currentIsSpace {154 if !atLineStart { pieces.append(Piece(text: current.replacingOccurrences(of: "\t", with: isCode ? " " : "\t"), styles: styles.filter { if case .link = $0 { return true } else { return false } }, isSpace: true)) }155 } else {156 pieces.append(Piece(text: isCode ? MarkdownWriter.codeSpan(current) : MarkdownWriter.escape(current, lineStart: atLineStart, braces: braces), styles: styles))157 atLineStart = false158 }159 current = ""160 }161 for ch in run.text {162 if ch == "\u{2028}" {163 flushCurrent()164 switch breaks {165 case .hard: pieces.append(Piece(text: "\\\n", styles: [], isBreak: true)); atLineStart = true166 case .html: pieces.append(Piece(text: "<br>", styles: []))167 case .space: pieces.append(Piece(text: " ", styles: [], isSpace: true))168 }169 continue170 }171 let space = ch == " " || ch == "\t"172 if isCode { current.append(ch); currentIsSpace = false; continue }173 if space != currentIsSpace { flushCurrent(); currentIsSpace = space }174 current.append(ch)175 }176 flushCurrent()177 }178 // Trailing white space and line breaks would be lost or misread.179 while let last = pieces.last, last.isSpace || last.isBreak { pieces.removeLast() }180181 var out = ""182 var open: [Sty] = []183 func marker(_ s: Sty, opening: Bool) -> String {184 switch s {185 case .link(let url): return opening ? "[" : "](\(MarkdownWriter.destination(url)))"186 case .bold: return "**"187 case .italic: return "*"188 case .strike: return "~~"189 case .underline: return opening ? "<u>" : "</u>"190 case .sub: return opening ? "<sub>" : "</sub>"191 case .sup: return opening ? "<sup>" : "</sup>"192 case .mark: return opening ? "<mark>" : "</mark>"193 }194 }195 func isDelimiter(_ s: Sty) -> Bool { s == .bold || s == .italic || s == .strike }196 func isPunctuationOrSpace(_ ch: Character?) -> Bool { ch.map { $0.isWhitespace || $0.isPunctuation || $0.isSymbol } ?? true }197 var lastContent: Character?198 for (k, piece) in pieces.enumerated() {199 var wanted = piece.styles200 if piece.isSpace || piece.isBreak {201 // White space keeps whatever is open and also wanted by the next word, so "**a b**" stays one span.202 let next = pieces[(k + 1)...].first { !$0.isSpace && !$0.isBreak }?.styles ?? []203 wanted = piece.isBreak ? [] : open.filter { next.contains($0) }204 }205 var keep = 0206 while keep < open.count, wanted.contains(open[keep]) { keep += 1 }207 let closing = Array(open[keep...].reversed())208 let opening = wanted.filter { !open[..<keep].contains($0) }209 let first = piece.text.first210 var closers = closing.map { marker($0, opening: false) }.joined()211 var openers = opening.map { marker($0, opening: true) }.joined()212 let closesDelimiter = closing.contains(where: isDelimiter), opensDelimiter = opening.contains(where: isDelimiter)213 if closesDelimiter {214 // A closing run must be right-flanking and must not merge with an opening run that follows it.215 let nextIsOpener = opensDelimiter216 let flankingFails = (lastContent.map { $0.isPunctuation || $0.isSymbol } ?? false) && !isPunctuationOrSpace(opening.isEmpty ? first : "<")217 if nextIsOpener || flankingFails { closers += "<!---->" }218 } else if opensDelimiter {219 let previous = out.last220 if !isPunctuationOrSpace(previous), let f = first, f.isPunctuation || f.isSymbol { openers = "<!---->" + openers }221 }222 // Two code spans (or a code span after a literal backtick) must not run into each other.223 if closers.isEmpty, openers.isEmpty, piece.text.hasPrefix("`"), out.hasSuffix("`") { openers = "<!---->" }224 out += closers + openers + piece.text225 open = Array(open[..<keep]) + opening226 if !piece.isSpace, !piece.isBreak { lastContent = piece.text.last }227 }228 out += open.reversed().map { marker($0, opening: false) }.joined()229 return out230 }231232 // MARK: Blocks233234 mutating func write() -> String {235 var chunks: [(text: String, tightWithPrevious: Bool)] = []236 func add(_ text: String, tight: Bool = false) { chunks.append((text, tight)) }237238 // Front matter.239 let meta = doc.meta240 func yaml(_ s: String) -> String { "\"" + s.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\"").replacingOccurrences(of: "\n", with: " ") + "\"" }241 var front: [String] = []242 if !meta.title.isEmpty { front.append("title: " + yaml(meta.title)) }243 if !meta.author.isEmpty { front.append("author: " + yaml(meta.author)) }244 if !meta.subject.isEmpty { front.append("subject: " + yaml(meta.subject)) }245 if !meta.keywords.isEmpty { front.append("keywords: [" + meta.keywords.map(yaml).joined(separator: ", ") + "]") }246 if !meta.language.isEmpty, meta.language != "en" { front.append("lang: " + yaml(meta.language)) }247 let frontMatter = front.isEmpty ? "" : "---\n" + front.joined(separator: "\n") + "\n---\n\n"248249 // List state.250 var counters: [String: [Int]] = [:]251 var listStack: [(offset: Int, content: Int)] = [] // marker column and content column per open level252 var previousList: (id: String, ordered: Bool)?253 var alternate = false254 var inList = false255256 let body = doc.body257 var index = 0258 while index < body.count {259 let block = body[index]260 index += 1261 switch block {262 case .paragraph(let p):263 if let item = p.list, let def = doc.list(item.listID), !def.levels.isEmpty {264 var level = max(0, min(def.levels.count - 1, item.level))265 level = min(level, inList ? listStack.count : 0)266 let ordered = def.levels[level].format != .bullet && def.levels[level].format != .none267 var levelCounters = counters[item.listID] ?? Array(repeating: 0, count: def.levels.count)268 levelCounters[level] = levelCounters[level] == 0 ? def.levels[level].start : levelCounters[level] + 1269 for deeper in (level + 1)..<levelCounters.count { levelCounters[deeper] = 0 }270 counters[item.listID] = levelCounters271 var newList = false272 if level == 0 {273 if let previous = previousList, previous.id != item.listID, inList {274 // A different list right after a list of the same flavour: switch marker style so parsers keep them apart.275 newList = true276 alternate = previous.ordered == ordered ? !alternate : false277 } else if !inList { alternate = false }278 previousList = (item.listID, ordered)279 }280 let marker = ordered ? "\(levelCounters[level])" + (alternate && level == 0 ? ")" : ".") : (alternate && level == 0 ? "*" : "-")281 let offset = level == 0 ? 0 : listStack[level - 1].content282 listStack = Array(listStack.prefix(level)) + [(offset, offset + marker.count + 1)]283 var text = inline(p)284 for (box, mark) in [("☐ ", "[ ] "), ("☑ ", "[x] "), ("☒ ", "[x] ")] where text.hasPrefix(box) { text = mark + text.dropFirst(box.count) }285 let pad = String(repeating: " ", count: offset)286 let continuation = String(repeating: " ", count: offset + marker.count + 1)287 add(pad + marker + " " + text.replacingOccurrences(of: "\n", with: "\n" + continuation), tight: inList && !newList)288 inList = true289 continue290 }291 if inList, p.style == StyleID.listParagraph, let left = p.props.indentLeft, left > 0, !listStack.isEmpty, !p.isEmpty {292 // Continuation paragraph of the current list item.293 let level = max(0, min(listStack.count - 1, Int(((left - 36) / 18).rounded())))294 let pad = String(repeating: " ", count: listStack[level].content)295 add(pad + inline(p).replacingOccurrences(of: "\n", with: "\n" + pad))296 continue297 }298 inList = false299 listStack = []300 if ModelIdiom.isRule(p) { add("---"); continue }301 if p.style == StyleID.code {302 var lines = [p.plainText]303 while index < body.count, case .paragraph(let next) = body[index], next.style == StyleID.code, next.list == nil { lines.append(next.plainText); index += 1 }304 let code = lines.joined(separator: "\n").replacingOccurrences(of: lineSeparatorCharacter, with: "\n").replacingOccurrences(of: objectReplacementCharacter, with: "")305 var longest = 2, current = 0306 for ch in code { if ch == "`" { current += 1; longest = max(longest, current) } else { current = 0 } }307 let fence = String(repeating: "`", count: longest + 1)308 add(fence + "\n" + code + "\n" + fence)309 continue310 }311 if let equation = ModelIdiom.displayEquation(p) { add("$$\n" + equation.latex + "\n$$"); continue }312 if p.style == StyleID.title || ModelIdiom.headingLevel(p, styles: doc.styles) != nil {313 let level = p.style == StyleID.title ? 1 : ModelIdiom.headingLevel(p, styles: doc.styles) ?? 1314 if level > 6 { ctx.warnings.add(.approximated, "Headings", "Heading levels 7 to 9 are written as level 6.") }315 if p.style == StyleID.title { ctx.warnings.add(.approximated, "Title", "The title paragraph is written as a level 1 heading.") }316 var anchor = ""317 var skip = false318 if let name = MarkdownWriter.anchorName(p) { anchor = " {#\(name)}"; skip = true }319 let number = MarkdownWriter.escape(ctx.headingNumberPrefix(p), lineStart: false)320 if !number.isEmpty { ctx.warnings.add(.approximated, "Heading numbers", "Automatic heading numbers are written as text.") }321 let text = inline(p, breaks: .space, braces: true, skipLeadingBookmark: skip)322 add(String(repeating: "#", count: min(6, level)) + " " + number + text + anchor)323 continue324 }325 if p.style == StyleID.quote {326 var parts = [inline(p)]327 while index < body.count, case .paragraph(let next) = body[index], next.style == StyleID.quote, next.list == nil { parts.append(inline(next)); index += 1 }328 add(parts.map { "> " + $0.replacingOccurrences(of: "\n", with: "\n> ") }.joined(separator: "\n>\n"))329 continue330 }331 let text = inline(p)332 if !text.isEmpty { add(text) }333 case .table(let t):334 inList = false; listStack = []335 add(table(t))336 case .pageBreak, .sectionBreak:337 inList = false; listStack = []338 case .toc(let toc):339 inList = false; listStack = []340 let entries = ctx.entries(of: toc)341 var lines: [String] = []342 let top = entries.map(\.level).min() ?? 1343 for e in entries {344 let label = MarkdownWriter.escape(e.text, lineStart: false)345 lines.append(String(repeating: " ", count: e.level - top) + "- " + (slugs[e.target].map { "[\(label)](#\($0))" } ?? label))346 }347 if let title = toc.title, !title.isEmpty { add("**" + MarkdownWriter.escape(title, lineStart: false) + "**") }348 if !lines.isEmpty { add(lines.joined(separator: "\n")) }349 case .bibliography(let b):350 inList = false; listStack = []351 if let title = b.title, !title.isEmpty { add("# " + MarkdownWriter.escape(title, lineStart: false)) }352 if let entries = ctx.bibliographyParagraphs() {353 for e in entries { let text = inline(e); if !text.isEmpty { add(text) } }354 } else {355 add("::: {#refs}\n:::")356 }357 }358 }359360 // Footnote definitions.361 for (ref, note) in ctx.orderedNotes {362 guard let label = noteLabels[ref.id] else { continue }363 var parts: [String] = []364 for p in note.paragraphs { let text = inline(p); if !text.isEmpty || parts.isEmpty { parts.append(text) } }365 add("[^\(label)]: " + parts.map { $0.replacingOccurrences(of: "\n", with: "\n ") }.joined(separator: "\n\n "))366 }367368 var out = frontMatter369 for (k, chunk) in chunks.enumerated() {370 if k > 0 { out += chunk.tightWithPrevious ? "\n" : "\n\n" }371 out += chunk.text372 }373 return out.isEmpty ? "" : out + "\n"374 }375376 private mutating func table(_ t: Table) -> String {377 let columns = max(1, t.columnCount)378 var rows: [[String]] = []379 var alignments = Array(repeating: "---", count: columns)380 for (r, row) in t.rows.enumerated() {381 var cells: [String] = []382 for cell in row.cells {383 var text = ""384 if cell.vMerge != .continue {385 text = cell.paragraphs.map { p in386 var s = inline(p, breaks: .html)387 if p.list != nil, let label = ctx.numbering.listLabels[p.id] { s = MarkdownWriter.escape(label, lineStart: true) + " " + s }388 return s389 }.filter { !$0.isEmpty }.joined(separator: "<br>").replacingOccurrences(of: "\n", with: " ")390 }391 if r == 0, cells.count < columns, let alignment = cell.paragraphs.first?.props.alignment {392 alignments[cells.count] = alignment == .center ? ":-:" : alignment == .right ? "--:" : alignment == .left ? ":--" : "---"393 }394 cells.append(text)395 for _ in 1..<max(1, cell.colSpan) { cells.append("") }396 }397 while cells.count < columns { cells.append("") }398 rows.append(Array(cells.prefix(columns)))399 }400 guard let header = rows.first else { return "" }401 if !(t.rows.first?.isHeader ?? false) { ctx.warnings.add(.approximated, "Tables", "Markdown tables always have a header row: the first row is written as the header.") }402 var lines = ["| " + header.joined(separator: " | ") + " |", "|" + alignments.map { " \($0) " }.joined(separator: "|") + "|"]403 for row in rows.dropFirst() { lines.append("| " + row.joined(separator: " | ") + " |") }404 return lines.joined(separator: "\n")405 }406}407