Commit `80ccfaf8c9`

80ccfaf8c917454fe4ee97304f85e512c2627b76

parent: ebd884b5da

Verified · cmc

cmc <hello@cleberg.net> · 2026-10-08 03:55 UTC

Markdown export: #+OPTIONS, export tags, #+INCLUDE, macros, Org file links

Markdown export preprocesses the text as the HTML page does (#+INCLUDE,
macros) and follows #+OPTIONS (todo, pri, tags, ^, title), the exclude
and select tags, COMMENT trees and archived trees, through the HTML
exporter's ExportOptions and section rule. file: links to .org files
point at .md without the search option, as ox-md writes them.

Layout: unified · split

Sources/OrgCore/Export/HTMLExport.swift +19 −7

         switch node.kind {
         case .section:
             guard let heading = node.firstChild(.heading) else { fallthrough }
-            let tags = heading.tokens.first { $0.kind == .tags }?.text.split(separator: ":").map(String.init) ?? []
+            switch Self.sectionExport(heading, options: options, selected: selected) {
-            let title = heading.firstChild(.title)?.text.trimmingCharacters(in: .whitespaces) ?? ""
+            case .nothing: return ""
-            // `org-export--skip-p`: excluded tags, COMMENT, unselected trees.
+            case .heading: return self.heading(heading)
-            if tags.contains(where: options.excludeTags.contains) || title == "COMMENT" || title.hasPrefix("COMMENT ") { return "" }
+            case .all: break
-            if let selected, !selected.contains(heading.range.lowerBound) { return "" }
+            }
-            // Archived trees export their heading only.
-            if tags.contains("ARCHIVE") { return self.heading(heading) }
             var out = ""
             for child in node.children { out += element(child) }
             return out
     /// `org-export--selected-trees`: headings with a select tag, everything below them and
     /// their ancestors; nil when no heading has one.
+    enum SectionExport {
+        case all, heading, nothing
+    }
+    /// `org-export--skip-p` for the section under `heading`: excluded tags, COMMENT and
+    /// unselected trees export nothing, archived trees their heading only.
+    static func sectionExport(_ heading: SyntaxNode, options: ExportOptions, selected: Set<Int>?) -> SectionExport {
+        let tags = heading.tokens.first { $0.kind == .tags }?.text.split(separator: ":").map(String.init) ?? []
+        let title = heading.firstChild(.title)?.text.trimmingCharacters(in: .whitespaces) ?? ""
+        if tags.contains(where: options.excludeTags.contains) || title == "COMMENT" || title.hasPrefix("COMMENT ") { return .nothing }
+        if let selected, !selected.contains(heading.range.lowerBound) { return .nothing }
+        return tags.contains("ARCHIVE") ? .heading : .all
+    }
     static func selection(_ tree: OrgTree, tags: [String]) -> Set<Int>? {
         let model = DocumentModel(tree: tree)
         let picked = model.headings.indices.filter { model.headings[$0].localTags.contains(where: tags.contains) }

Sources/OrgCore/Export/MarkdownExport.swift +34 −12

 /// Markdown export, GitHub-flavored: ATX headings, fenced code, pipe tables, task lists and
 /// `[^n]` footnotes. The title, when there is one, becomes the top heading.
 public enum MarkdownExport {
-    /// `path` is the file's, for `#+bibliography:`.
+    /// As the HTML page: `#+INCLUDE`, macros, `#+OPTIONS` and the select and exclude tags.
-    public static func document(_ text: String, settings: OrgSettings = .default, path: String? = nil) -> String {
+    /// `path` is the file's, for `#+INCLUDE`, `{{{input-file}}}` and `#+bibliography:`.
-        let renderer = MarkdownRenderer(settings: settings)
+    public static func document(_ text: String, settings: OrgSettings = .default, path: String? = nil, now: Date = Date()) -> String {
+        let directory = path.map { URL(fileURLWithPath: $0).deletingLastPathComponent() }
+        let text = ExportPreprocess.macros(ExportPreprocess.includes(text, directory: directory), path: path, now: now, setup: settings.setupKeywords)
+        let options = ExportOptions.parse(settings.setupKeywords + text)
+        let renderer = MarkdownRenderer(settings: settings, options: options)
         var out = ""
         renderer.inTitle = true
-        if let title = HTMLExport.metadata(text, settings: settings).title { out = "# " + renderer.inlineString(title) + "\n\n" }
+        if options.title, let title = HTMLExport.metadata(text, settings: settings).title { out = "# " + renderer.inlineString(title) + "\n\n" }
         renderer.inTitle = false
-        renderer.citations = CiteProcessor(text: text, directory: path.map { URL(fileURLWithPath: $0).deletingLastPathComponent() })
+        renderer.citations = CiteProcessor(text: text, directory: directory)
         out += renderer.document(renderer.citations == nil ? text : renderer.citations!.inliningNotes(CiteProcessor.removingNocite(text)))
         return out.trimmingCharacters(in: .newlines) + "\n"
     }
 final class MarkdownRenderer {
     let settings: OrgSettings
+    let options: ExportOptions
+    /// With select tags in the document: the sections to export, by heading start.
+    private var selected: Set<Int>?
     private var definitions: [String: String] = [:]
     private var numbers: [String: Int] = [:]
     private var notes: [(Int, String)] = []
     /// Rendering the title, where Org exports citations as nothing.
     var inTitle = false
-    init(settings: OrgSettings) {
+    init(settings: OrgSettings, options: ExportOptions) {
         self.settings = settings
+        self.options = options
     }
     func document(_ text: String) -> String {
                 definitions[String(m.1)] = String(node.text[m.range.upperBound...]).trimmingCharacters(in: .whitespacesAndNewlines)
             }
         }
+        selected = HTMLRenderer.selection(tree, tags: options.selectTags)
         var out = rendering(tree, text) { blocks(tree.root) }
         if !notes.isEmpty {
             out += notes.map { "[^\($0.0)]: " + $0.1 }.joined(separator: "\n") + "\n"
     private func element(_ node: SyntaxNode, indent: String) -> String {
         switch node.kind {
         case .zerothSection, .section:
+            if node.kind == .section, let heading = node.firstChild(.heading) {
+                switch HTMLRenderer.sectionExport(heading, options: options, selected: selected) {
+                case .nothing: return ""
+                case .heading: return element(heading, indent: indent)
+                case .all: break
+                }
+            }
             return blocks(node, indent: indent).trimmingCharacters(in: .newlines)
         case .heading:
             let level = node.tokens.first { $0.kind == .stars }?.text.count ?? 1
             var parts: [String] = []
-            if let todo = node.tokens.first(where: { $0.kind == .todoKeyword })?.text { parts.append(todo) }
+            if options.todo, let todo = node.tokens.first(where: { $0.kind == .todoKeyword })?.text { parts.append(todo) }
-            if let priority = node.tokens.first(where: { $0.kind == .priority })?.text { parts.append(priority) }
+            if options.priority, let priority = node.tokens.first(where: { $0.kind == .priority })?.text { parts.append(priority) }
             if let title = node.firstChild(.title) { parts.append(inline(title).trimmingCharacters(in: .whitespaces)) }
-            if let tags = node.tokens.first(where: { $0.kind == .tags })?.text {
+            if options.tags, let tags = node.tokens.first(where: { $0.kind == .tags })?.text {
                 parts.append(tags.split(separator: ":").map { "`\($0)`" }.joined(separator: " "))
             }
             return String(repeating: "#", count: min(level + 1, 6)) + " " + parts.filter { !$0.isEmpty }.joined(separator: " ")
             return String(node.text.dropFirst(3).dropLast(3))
         case .superscript, .subscript:
             let body = node.text.dropFirst()
-            let inner = body.hasPrefix("{") && body.hasSuffix("}") ? String(body.dropFirst().dropLast()) : String(body)
+            let braced = body.hasPrefix("{") && body.hasSuffix("}")
+            if options.scripts == .off || (options.scripts == .braces && !braced) { return node.text }
+            let inner = braced ? String(body.dropFirst().dropLast()) : String(body)
             return node.text.hasPrefix("_") ? "<sub>\(inner)</sub>" : "<sup>\(inner)</sup>"
         case .lineBreak: return "  \n"
         case .macro:
             return "<\(target)>"
         }
         var href = path
-        if path.hasPrefix("file:") { href = String(path.dropFirst(5)) }
+        if path.hasPrefix("file:") {
+            // ox-md drops the search option and, as `org-md-link-org-files-as-md`, writes .org as .md.
+            href = String(path.dropFirst(5))
+            if let search = href.range(of: "::") { href = String(href[..<search.lowerBound]) }
+        }
         if path.hasPrefix("id:") { href = "#" + path.dropFirst(3) }
-        if !path.contains(":"), href.lowercased().hasSuffix(".org") { href = String(href.dropLast(4)) + ".md" }
+        if !path.contains(":") || path.hasPrefix("file:"), href.lowercased().hasSuffix(".org") { href = String(href.dropLast(4)) + ".md" }
         if let description = node.firstChild(.linkDescription) { return "[\(inline(description))](\(href))" }
         let ext = href.split(separator: ".").last.map { $0.lowercased() } ?? ""
         if HTMLRenderer.imageExtensions.contains(ext) { return "![](\(href))" }

Tests/OrgCoreTests/ExportTests.swift +42

	@@ -168,6 +168,48 @@ struct MarkdownExportTests {
168	let ours = MarkdownExport.document(org)	168	let ours = MarkdownExport.document(org)
169	#expect(ours == expected)	169	#expect(ours == expected)
170	}	170	}
		171
		172	/// Words that ox-md keeps or drops for `#+OPTIONS`, the tags, COMMENT, `#+INCLUDE` and
		173	/// macros, and where links to Org files point.
		174	@Test(.enabled(if: ProcessInfo.processInfo.environment["ORGSTAR_SKIP_ORACLE"] == nil))
		175	func documentLevelLikeOrgMd() throws {
		176	let folder = FileManager.default.temporaryDirectory.appendingPathComponent("orgstar-md-\(UUID().uuidString)")
		177	try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
		178	defer { try? FileManager.default.removeItem(at: folder) }
		179	try "* Included\nwordincluded\n".write(to: folder.appendingPathComponent("part.org"), atomically: true, encoding: .utf8)
		180	let text = """
		181	#+TITLE: wordtitle
		182	#+OPTIONS: todo:nil tags:nil ^:nil toc:nil num:nil
		183	#+EXCLUDE_TAGS: private
		184	#+MACRO: greet wordmacro $1
		185	{{{greet(wordarg)}}} a_wordsub
		186	* TODO wordtodo :wordtag:
		187	* Kept :noexport:
		188	wordnoexport
		189	* Private :private:
		190	wordprivate
		191	* COMMENT Hidden
		192	wordcomment
		193	* Links
		194	[[file:x.org]] [[file:x.org][X]] [[./y.org]] [[file:sub/z.ORG::*Head][Z]]
		195	#+INCLUDE: "part.org"
		196	""" + "\n"
		197	let path = folder.appendingPathComponent("main.org").path
		198	try text.write(toFile: path, atomically: true, encoding: .utf8)
		199	let emacs = try EmacsOracle.evaluate(text, """
		200	(with-current-buffer (find-file-noselect \(Babel.lispString(path)))
		201	(require 'ox-md)
		202	(list (org-export-as 'md)))
		203	""")[0]
		204	let ours = MarkdownExport.document(text, path: path)
		205	// ox-md writes no title; this export makes it the top heading.
		206	for word in text.matches(of: /\bword[a-z]+\b\|\bTODO\b/).map({ String($0.0) }) where word != "wordtitle" {
		207	#expect(ours.contains(word) == emacs.contains(word), "\(word)\nours:\n\(ours)\nemacs:\n\(emacs)")
		208	}
		209	#expect(ours.contains("<sub>") == emacs.contains("<sub>"))
		210	let targets = { (s: String) in Set(s.matches(of: /[\w.\/]+\.(?:md\|org\|ORG)\b/).map { String($0.0) }) }
		211	#expect(targets(ours) == targets(emacs), "ours:\n\(ours)\nemacs:\n\(emacs)")
		212	}
171	}	213	}
172		214
173	struct ExportCorpusTests {	215	struct ExportCorpusTests {

Commit 80ccfaf8c9

Commit `80ccfaf8c9`