SPB Git

Repository Public

MarkdownExporter.swift 23.7 KB 407 lines swift

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("![\(alt)](\(ctx.options.imagePath?(asset) ?? 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
Files main
Menu

Theme