ox-md.el 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569
  1. ;;; ox-md.el --- Markdown Back-End for Org Export Engine
  2. ;; Copyright (C) 2012-2015 Free Software Foundation, Inc.
  3. ;; Author: Nicolas Goaziou <n.goaziou@gmail.com>
  4. ;; Keywords: org, wp, markdown
  5. ;; This file is part of GNU Emacs.
  6. ;; GNU Emacs is free software: you can redistribute it and/or modify
  7. ;; it under the terms of the GNU General Public License as published by
  8. ;; the Free Software Foundation, either version 3 of the License, or
  9. ;; (at your option) any later version.
  10. ;; GNU Emacs is distributed in the hope that it will be useful,
  11. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. ;; GNU General Public License for more details.
  14. ;; You should have received a copy of the GNU General Public License
  15. ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
  16. ;;; Commentary:
  17. ;; This library implements a Markdown back-end (vanilla flavor) for
  18. ;; Org exporter, based on `html' back-end. See Org manual for more
  19. ;; information.
  20. ;;; Code:
  21. (eval-when-compile (require 'cl))
  22. (require 'ox-html)
  23. (require 'ox-publish)
  24. ;;; User-Configurable Variables
  25. (defgroup org-export-md nil
  26. "Options specific to Markdown export back-end."
  27. :tag "Org Markdown"
  28. :group 'org-export
  29. :version "24.4"
  30. :package-version '(Org . "8.0"))
  31. (defcustom org-md-headline-style 'atx
  32. "Style used to format headlines.
  33. This variable can be set to either `atx' or `setext'."
  34. :group 'org-export-md
  35. :type '(choice
  36. (const :tag "Use \"atx\" style" atx)
  37. (const :tag "Use \"Setext\" style" setext)))
  38. ;;; Define Back-End
  39. (org-export-define-derived-backend 'md 'html
  40. :export-block '("MD" "MARKDOWN")
  41. :filters-alist '((:filter-parse-tree . org-md-separate-elements))
  42. :menu-entry
  43. '(?m "Export to Markdown"
  44. ((?M "To temporary buffer"
  45. (lambda (a s v b) (org-md-export-as-markdown a s v)))
  46. (?m "To file" (lambda (a s v b) (org-md-export-to-markdown a s v)))
  47. (?o "To file and open"
  48. (lambda (a s v b)
  49. (if a (org-md-export-to-markdown t s v)
  50. (org-open-file (org-md-export-to-markdown nil s v)))))))
  51. :translate-alist '((bold . org-md-bold)
  52. (code . org-md-verbatim)
  53. (example-block . org-md-example-block)
  54. (export-block . org-md-export-block)
  55. (fixed-width . org-md-example-block)
  56. (headline . org-md-headline)
  57. (horizontal-rule . org-md-horizontal-rule)
  58. (inline-src-block . org-md-verbatim)
  59. (inner-template . org-md-inner-template)
  60. (italic . org-md-italic)
  61. (item . org-md-item)
  62. (keyword . org-md-keyword)
  63. (line-break . org-md-line-break)
  64. (link . org-md-link)
  65. (node-property . org-md-node-property)
  66. (paragraph . org-md-paragraph)
  67. (plain-list . org-md-plain-list)
  68. (plain-text . org-md-plain-text)
  69. (property-drawer . org-md-property-drawer)
  70. (quote-block . org-md-quote-block)
  71. (section . org-md-section)
  72. (src-block . org-md-example-block)
  73. (template . org-md-template)
  74. (verbatim . org-md-verbatim))
  75. :options-alist '((:md-headline-style nil nil org-md-headline-style)))
  76. ;;; Filters
  77. (defun org-md-separate-elements (tree backend info)
  78. "Fix blank lines between elements.
  79. TREE is the parse tree being exported. BACKEND is the export
  80. back-end used. INFO is a plist used as a communication channel.
  81. Enforce a blank line between elements. There are two exceptions
  82. to this rule:
  83. 1. Preserve blank lines between sibling items in a plain list,
  84. 2. In an item, remove any blank line before the very first
  85. paragraph and the next sub-list when the latter ends the
  86. current item.
  87. Assume BACKEND is `md'."
  88. (org-element-map tree (remq 'item org-element-all-elements)
  89. (lambda (e)
  90. (org-element-put-property
  91. e :post-blank
  92. (if (and (eq (org-element-type e) 'paragraph)
  93. (eq (org-element-type (org-element-property :parent e)) 'item)
  94. (org-export-first-sibling-p e info)
  95. (let ((next (org-export-get-next-element e info)))
  96. (and (eq (org-element-type next) 'plain-list)
  97. (not (org-export-get-next-element next info)))))
  98. 0
  99. 1))))
  100. ;; Return updated tree.
  101. tree)
  102. ;;; Transcode Functions
  103. ;;;; Bold
  104. (defun org-md-bold (bold contents info)
  105. "Transcode BOLD object into Markdown format.
  106. CONTENTS is the text within bold markup. INFO is a plist used as
  107. a communication channel."
  108. (format "**%s**" contents))
  109. ;;;; Code and Verbatim
  110. (defun org-md-verbatim (verbatim contents info)
  111. "Transcode VERBATIM object into Markdown format.
  112. CONTENTS is nil. INFO is a plist used as a communication
  113. channel."
  114. (let ((value (org-element-property :value verbatim)))
  115. (format (cond ((not (string-match "`" value)) "`%s`")
  116. ((or (string-match "\\``" value)
  117. (string-match "`\\'" value))
  118. "`` %s ``")
  119. (t "``%s``"))
  120. value)))
  121. ;;;; Example Block, Src Block and export Block
  122. (defun org-md-example-block (example-block contents info)
  123. "Transcode EXAMPLE-BLOCK element into Markdown format.
  124. CONTENTS is nil. INFO is a plist used as a communication
  125. channel."
  126. (replace-regexp-in-string
  127. "^" " "
  128. (org-remove-indentation
  129. (org-export-format-code-default example-block info))))
  130. (defun org-md-export-block (export-block contents info)
  131. "Transcode a EXPORT-BLOCK element from Org to Markdown.
  132. CONTENTS is nil. INFO is a plist holding contextual information."
  133. (if (member (org-element-property :type export-block) '("MARKDOWN" "MD"))
  134. (org-remove-indentation (org-element-property :value export-block))
  135. ;; Also include HTML export blocks.
  136. (org-export-with-backend 'html export-block contents info)))
  137. ;;;; Headline
  138. (defun org-md-headline (headline contents info)
  139. "Transcode HEADLINE element into Markdown format.
  140. CONTENTS is the headline contents. INFO is a plist used as
  141. a communication channel."
  142. (unless (org-element-property :footnote-section-p headline)
  143. (let* ((level (org-export-get-relative-level headline info))
  144. (title (org-export-data (org-element-property :title headline) info))
  145. (todo (and (plist-get info :with-todo-keywords)
  146. (let ((todo (org-element-property :todo-keyword
  147. headline)))
  148. (and todo (concat (org-export-data todo info) " ")))))
  149. (tags (and (plist-get info :with-tags)
  150. (let ((tag-list (org-export-get-tags headline info)))
  151. (and tag-list
  152. (format " :%s:"
  153. (mapconcat 'identity tag-list ":"))))))
  154. (priority
  155. (and (plist-get info :with-priority)
  156. (let ((char (org-element-property :priority headline)))
  157. (and char (format "[#%c] " char)))))
  158. (anchor
  159. (and (plist-get info :with-toc)
  160. (format "<a id=\"%s\"></a>"
  161. (or (org-element-property :CUSTOM_ID headline)
  162. (org-export-get-reference headline info)))))
  163. ;; Headline text without tags.
  164. (heading (concat todo priority title))
  165. (style (plist-get info :md-headline-style)))
  166. (cond
  167. ;; Cannot create a headline. Fall-back to a list.
  168. ((or (org-export-low-level-p headline info)
  169. (not (memq style '(atx setext)))
  170. (and (eq style 'atx) (> level 6))
  171. (and (eq style 'setext) (> level 2)))
  172. (let ((bullet
  173. (if (not (org-export-numbered-headline-p headline info)) "-"
  174. (concat (number-to-string
  175. (car (last (org-export-get-headline-number
  176. headline info))))
  177. "."))))
  178. (concat bullet (make-string (- 4 (length bullet)) ?\s) heading tags
  179. "\n\n"
  180. (and contents
  181. (replace-regexp-in-string "^" " " contents)))))
  182. ;; Use "Setext" style.
  183. ((eq style 'setext)
  184. (concat heading tags anchor "\n"
  185. (make-string (length heading) (if (= level 1) ?= ?-))
  186. "\n\n"
  187. contents))
  188. ;; Use "atx" style.
  189. (t (concat (make-string level ?#) " " heading tags anchor "\n\n"
  190. contents))))))
  191. ;;;; Horizontal Rule
  192. (defun org-md-horizontal-rule (horizontal-rule contents info)
  193. "Transcode HORIZONTAL-RULE element into Markdown format.
  194. CONTENTS is the horizontal rule contents. INFO is a plist used
  195. as a communication channel."
  196. "---")
  197. ;;;; Italic
  198. (defun org-md-italic (italic contents info)
  199. "Transcode ITALIC object into Markdown format.
  200. CONTENTS is the text within italic markup. INFO is a plist used
  201. as a communication channel."
  202. (format "*%s*" contents))
  203. ;;;; Item
  204. (defun org-md-item (item contents info)
  205. "Transcode ITEM element into Markdown format.
  206. CONTENTS is the item contents. INFO is a plist used as
  207. a communication channel."
  208. (let* ((type (org-element-property :type (org-export-get-parent item)))
  209. (struct (org-element-property :structure item))
  210. (bullet (if (not (eq type 'ordered)) "-"
  211. (concat (number-to-string
  212. (car (last (org-list-get-item-number
  213. (org-element-property :begin item)
  214. struct
  215. (org-list-prevs-alist struct)
  216. (org-list-parents-alist struct)))))
  217. "."))))
  218. (concat bullet
  219. (make-string (- 4 (length bullet)) ? )
  220. (case (org-element-property :checkbox item)
  221. (on "[X] ")
  222. (trans "[-] ")
  223. (off "[ ] "))
  224. (let ((tag (org-element-property :tag item)))
  225. (and tag (format "**%s:** "(org-export-data tag info))))
  226. (and contents
  227. (org-trim (replace-regexp-in-string "^" " " contents))))))
  228. ;;;; Keyword
  229. (defun org-md-keyword (keyword contents info)
  230. "Transcode a KEYWORD element into Markdown format.
  231. CONTENTS is nil. INFO is a plist used as a communication
  232. channel."
  233. (if (member (org-element-property :key keyword) '("MARKDOWN" "MD"))
  234. (org-element-property :value keyword)
  235. (org-export-with-backend 'html keyword contents info)))
  236. ;;;; Line Break
  237. (defun org-md-line-break (line-break contents info)
  238. "Transcode LINE-BREAK object into Markdown format.
  239. CONTENTS is nil. INFO is a plist used as a communication
  240. channel."
  241. " \n")
  242. ;;;; Link
  243. (defun org-md-link (link contents info)
  244. "Transcode LINE-BREAK object into Markdown format.
  245. CONTENTS is the link's description. INFO is a plist used as
  246. a communication channel."
  247. (let ((link-org-files-as-md
  248. (lambda (raw-path)
  249. ;; Treat links to `file.org' as links to `file.md'.
  250. (if (string= ".org" (downcase (file-name-extension raw-path ".")))
  251. (concat (file-name-sans-extension raw-path) ".md")
  252. raw-path)))
  253. (type (org-element-property :type link)))
  254. (cond
  255. ;; Link type is handled by a special function.
  256. ((org-export-custom-protocol-maybe link contents 'md))
  257. ((member type '("custom-id" "id" "fuzzy"))
  258. (let ((destination (if (string= type "fuzzy")
  259. (org-export-resolve-fuzzy-link link info)
  260. (org-export-resolve-id-link link info))))
  261. (case (org-element-type destination)
  262. (plain-text ; External file.
  263. (let ((path (funcall link-org-files-as-md destination)))
  264. (if (not contents) (format "<%s>" path)
  265. (format "[%s](%s)" contents path))))
  266. (headline
  267. (format
  268. "[%s](#%s)"
  269. ;; Description.
  270. (cond ((org-string-nw-p contents))
  271. ((org-export-numbered-headline-p destination info)
  272. (mapconcat #'number-to-string
  273. (org-export-get-headline-number destination info)
  274. "."))
  275. (t (org-export-data (org-element-property :title destination)
  276. info)))
  277. ;; Reference.
  278. (or (org-element-property :CUSTOM_ID destination)
  279. (org-export-get-reference destination info))))
  280. (t
  281. (let ((description
  282. (or (org-string-nw-p contents)
  283. (let ((number (org-export-get-ordinal destination info)))
  284. (cond
  285. ((not number) nil)
  286. ((atom number) (number-to-string number))
  287. (t (mapconcat #'number-to-string number ".")))))))
  288. (when description
  289. (format "[%s](#%s)"
  290. description
  291. (org-export-get-reference destination info))))))))
  292. ((org-export-inline-image-p link org-html-inline-image-rules)
  293. (let ((path (let ((raw-path (org-element-property :path link)))
  294. (if (not (file-name-absolute-p raw-path)) raw-path
  295. (expand-file-name raw-path))))
  296. (caption (org-export-data
  297. (org-export-get-caption
  298. (org-export-get-parent-element link)) info)))
  299. (format "![img](%s)"
  300. (if (not (org-string-nw-p caption)) path
  301. (format "%s \"%s\"" path caption)))))
  302. ((string= type "coderef")
  303. (let ((ref (org-element-property :path link)))
  304. (format (org-export-get-coderef-format ref contents)
  305. (org-export-resolve-coderef ref info))))
  306. ((equal type "radio") contents)
  307. (t (let* ((raw-path (org-element-property :path link))
  308. (path
  309. (cond
  310. ((member type '("http" "https" "ftp"))
  311. (concat type ":" raw-path))
  312. ((string= type "file")
  313. (org-export-file-uri (funcall link-org-files-as-md raw-path)))
  314. (t raw-path))))
  315. (if (not contents) (format "<%s>" path)
  316. (format "[%s](%s)" contents path)))))))
  317. ;;;; Node Property
  318. (defun org-md-node-property (node-property contents info)
  319. "Transcode a NODE-PROPERTY element into Markdown syntax.
  320. CONTENTS is nil. INFO is a plist holding contextual
  321. information."
  322. (format "%s:%s"
  323. (org-element-property :key node-property)
  324. (let ((value (org-element-property :value node-property)))
  325. (if value (concat " " value) ""))))
  326. ;;;; Paragraph
  327. (defun org-md-paragraph (paragraph contents info)
  328. "Transcode PARAGRAPH element into Markdown format.
  329. CONTENTS is the paragraph contents. INFO is a plist used as
  330. a communication channel."
  331. (let ((first-object (car (org-element-contents paragraph))))
  332. ;; If paragraph starts with a #, protect it.
  333. (if (and (stringp first-object) (string-match "\\`#" first-object))
  334. (replace-regexp-in-string "\\`#" "\\#" contents nil t)
  335. contents)))
  336. ;;;; Plain List
  337. (defun org-md-plain-list (plain-list contents info)
  338. "Transcode PLAIN-LIST element into Markdown format.
  339. CONTENTS is the plain-list contents. INFO is a plist used as
  340. a communication channel."
  341. contents)
  342. ;;;; Plain Text
  343. (defun org-md-plain-text (text info)
  344. "Transcode a TEXT string into Markdown format.
  345. TEXT is the string to transcode. INFO is a plist holding
  346. contextual information."
  347. (when (plist-get info :with-smart-quotes)
  348. (setq text (org-export-activate-smart-quotes text :html info)))
  349. ;; Protect ambiguous #. This will protect # at the beginning of
  350. ;; a line, but not at the beginning of a paragraph. See
  351. ;; `org-md-paragraph'.
  352. (setq text (replace-regexp-in-string "\n#" "\n\\\\#" text))
  353. ;; Protect ambiguous !
  354. (setq text (replace-regexp-in-string "\\(!\\)\\[" "\\\\!" text nil nil 1))
  355. ;; Protect `, *, _ and \
  356. (setq text (replace-regexp-in-string "[`*_\\]" "\\\\\\&" text))
  357. ;; Handle special strings, if required.
  358. (when (plist-get info :with-special-strings)
  359. (setq text (org-html-convert-special-strings text)))
  360. ;; Handle break preservation, if required.
  361. (when (plist-get info :preserve-breaks)
  362. (setq text (replace-regexp-in-string "[ \t]*\n" " \n" text)))
  363. ;; Return value.
  364. text)
  365. ;;;; Property Drawer
  366. (defun org-md-property-drawer (property-drawer contents info)
  367. "Transcode a PROPERTY-DRAWER element into Markdown format.
  368. CONTENTS holds the contents of the drawer. INFO is a plist
  369. holding contextual information."
  370. (and (org-string-nw-p contents)
  371. (replace-regexp-in-string "^" " " contents)))
  372. ;;;; Quote Block
  373. (defun org-md-quote-block (quote-block contents info)
  374. "Transcode QUOTE-BLOCK element into Markdown format.
  375. CONTENTS is the quote-block contents. INFO is a plist used as
  376. a communication channel."
  377. (replace-regexp-in-string
  378. "^" "> "
  379. (replace-regexp-in-string "\n\\'" "" contents)))
  380. ;;;; Section
  381. (defun org-md-section (section contents info)
  382. "Transcode SECTION element into Markdown format.
  383. CONTENTS is the section contents. INFO is a plist used as
  384. a communication channel."
  385. contents)
  386. ;;;; Template
  387. (defun org-md-inner-template (contents info)
  388. "Return body of document after converting it to Markdown syntax.
  389. CONTENTS is the transcoded contents string. INFO is a plist
  390. holding export options."
  391. ;; Make sure CONTENTS is separated from table of contents and
  392. ;; footnotes with at least a blank line.
  393. (org-trim (org-html-inner-template (concat "\n" contents "\n") info)))
  394. (defun org-md-template (contents info)
  395. "Return complete document string after Markdown conversion.
  396. CONTENTS is the transcoded contents string. INFO is a plist used
  397. as a communication channel."
  398. contents)
  399. ;;; Interactive function
  400. ;;;###autoload
  401. (defun org-md-export-as-markdown (&optional async subtreep visible-only)
  402. "Export current buffer to a Markdown buffer.
  403. If narrowing is active in the current buffer, only export its
  404. narrowed part.
  405. If a region is active, export that region.
  406. A non-nil optional argument ASYNC means the process should happen
  407. asynchronously. The resulting buffer should be accessible
  408. through the `org-export-stack' interface.
  409. When optional argument SUBTREEP is non-nil, export the sub-tree
  410. at point, extracting information from the headline properties
  411. first.
  412. When optional argument VISIBLE-ONLY is non-nil, don't export
  413. contents of hidden elements.
  414. Export is done in a buffer named \"*Org MD Export*\", which will
  415. be displayed when `org-export-show-temporary-export-buffer' is
  416. non-nil."
  417. (interactive)
  418. (org-export-to-buffer 'md "*Org MD Export*"
  419. async subtreep visible-only nil nil (lambda () (text-mode))))
  420. ;;;###autoload
  421. (defun org-md-convert-region-to-md ()
  422. "Assume the current region has org-mode syntax, and convert it to Markdown.
  423. This can be used in any buffer. For example, you can write an
  424. itemized list in org-mode syntax in a Markdown buffer and use
  425. this command to convert it."
  426. (interactive)
  427. (org-export-replace-region-by 'md))
  428. ;;;###autoload
  429. (defun org-md-export-to-markdown (&optional async subtreep visible-only)
  430. "Export current buffer to a Markdown file.
  431. If narrowing is active in the current buffer, only export its
  432. narrowed part.
  433. If a region is active, export that region.
  434. A non-nil optional argument ASYNC means the process should happen
  435. asynchronously. The resulting file should be accessible through
  436. the `org-export-stack' interface.
  437. When optional argument SUBTREEP is non-nil, export the sub-tree
  438. at point, extracting information from the headline properties
  439. first.
  440. When optional argument VISIBLE-ONLY is non-nil, don't export
  441. contents of hidden elements.
  442. Return output file's name."
  443. (interactive)
  444. (let ((outfile (org-export-output-file-name ".md" subtreep)))
  445. (org-export-to-file 'md outfile async subtreep visible-only)))
  446. ;;;###autoload
  447. (defun org-md-publish-to-md (plist filename pub-dir)
  448. "Publish an org file to Markdown.
  449. FILENAME is the filename of the Org file to be published. PLIST
  450. is the property list for the given project. PUB-DIR is the
  451. publishing directory.
  452. Return output file name."
  453. (org-publish-org-to 'md filename ".md" plist pub-dir))
  454. (provide 'ox-md)
  455. ;; Local variables:
  456. ;; generated-autoload-file: "org-loaddefs.el"
  457. ;; End:
  458. ;;; ox-md.el ends here