1 ;;; ox-md.el --- Markdown Back-End for Org Export Engine -*- lexical-binding: t; -*-
3 ;; Copyright (C) 2012-2016 Free Software Foundation, Inc.
5 ;; Author: Nicolas Goaziou <n.goaziou@gmail.com>
6 ;; Keywords: org, wp, markdown
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
25 ;; This library implements a Markdown back-end (vanilla flavor) for
26 ;; Org exporter, based on `html' back-end. See Org manual for more
36 ;;; User-Configurable Variables
38 (defgroup org-export-md nil
39 "Options specific to Markdown export back-end."
43 :package-version
'(Org .
"8.0"))
45 (defcustom org-md-headline-style
'atx
46 "Style used to format headlines.
47 This variable can be set to either `atx' or `setext'."
50 (const :tag
"Use \"atx\" style" atx
)
51 (const :tag
"Use \"Setext\" style" setext
)))
57 (org-export-define-derived-backend 'md
'html
58 :filters-alist
'((:filter-parse-tree . org-md-separate-elements
))
60 '(?m
"Export to Markdown"
61 ((?M
"To temporary buffer"
62 (lambda (a s v b
) (org-md-export-as-markdown a s v
)))
63 (?m
"To file" (lambda (a s v b
) (org-md-export-to-markdown a s v
)))
64 (?o
"To file and open"
66 (if a
(org-md-export-to-markdown t s v
)
67 (org-open-file (org-md-export-to-markdown nil s v
)))))))
68 :translate-alist
'((bold . org-md-bold
)
69 (code . org-md-verbatim
)
70 (example-block . org-md-example-block
)
71 (export-block . org-md-export-block
)
72 (fixed-width . org-md-example-block
)
73 (headline . org-md-headline
)
74 (horizontal-rule . org-md-horizontal-rule
)
75 (inline-src-block . org-md-verbatim
)
76 (inner-template . org-md-inner-template
)
77 (italic . org-md-italic
)
79 (keyword . org-md-keyword
)
80 (line-break . org-md-line-break
)
82 (node-property . org-md-node-property
)
83 (paragraph . org-md-paragraph
)
84 (plain-list . org-md-plain-list
)
85 (plain-text . org-md-plain-text
)
86 (property-drawer . org-md-property-drawer
)
87 (quote-block . org-md-quote-block
)
88 (section . org-md-section
)
89 (src-block . org-md-example-block
)
90 (template . org-md-template
)
91 (verbatim . org-md-verbatim
))
92 :options-alist
'((:md-headline-style nil nil org-md-headline-style
)))
97 (defun org-md-separate-elements (tree _backend info
)
98 "Fix blank lines between elements.
100 TREE is the parse tree being exported. BACKEND is the export
101 back-end used. INFO is a plist used as a communication channel.
103 Enforce a blank line between elements. There are two exceptions
106 1. Preserve blank lines between sibling items in a plain list,
108 2. In an item, remove any blank line before the very first
109 paragraph and the next sub-list when the latter ends the
112 Assume BACKEND is `md'."
113 (org-element-map tree
(remq 'item org-element-all-elements
)
115 (org-element-put-property
117 (if (and (eq (org-element-type e
) 'paragraph
)
118 (eq (org-element-type (org-element-property :parent e
)) 'item
)
119 (org-export-first-sibling-p e info
)
120 (let ((next (org-export-get-next-element e info
)))
121 (and (eq (org-element-type next
) 'plain-list
)
122 (not (org-export-get-next-element next info
)))))
125 ;; Return updated tree.
130 ;;; Transcode Functions
134 (defun org-md-bold (_bold contents _info
)
135 "Transcode BOLD object into Markdown format.
136 CONTENTS is the text within bold markup. INFO is a plist used as
137 a communication channel."
138 (format "**%s**" contents
))
141 ;;;; Code and Verbatim
143 (defun org-md-verbatim (verbatim _contents _info
)
144 "Transcode VERBATIM object into Markdown format.
145 CONTENTS is nil. INFO is a plist used as a communication
147 (let ((value (org-element-property :value verbatim
)))
148 (format (cond ((not (string-match "`" value
)) "`%s`")
149 ((or (string-match "\\``" value
)
150 (string-match "`\\'" value
))
156 ;;;; Example Block, Src Block and export Block
158 (defun org-md-example-block (example-block _contents info
)
159 "Transcode EXAMPLE-BLOCK element into Markdown format.
160 CONTENTS is nil. INFO is a plist used as a communication
162 (replace-regexp-in-string
164 (org-remove-indentation
165 (org-export-format-code-default example-block info
))))
167 (defun org-md-export-block (export-block contents info
)
168 "Transcode a EXPORT-BLOCK element from Org to Markdown.
169 CONTENTS is nil. INFO is a plist holding contextual information."
170 (if (member (org-element-property :type export-block
) '("MARKDOWN" "MD"))
171 (org-remove-indentation (org-element-property :value export-block
))
172 ;; Also include HTML export blocks.
173 (org-export-with-backend 'html export-block contents info
)))
178 (defun org-md-headline (headline contents info
)
179 "Transcode HEADLINE element into Markdown format.
180 CONTENTS is the headline contents. INFO is a plist used as
181 a communication channel."
182 (unless (org-element-property :footnote-section-p headline
)
183 (let* ((level (org-export-get-relative-level headline info
))
184 (title (org-export-data (org-element-property :title headline
) info
))
185 (todo (and (plist-get info
:with-todo-keywords
)
186 (let ((todo (org-element-property :todo-keyword
188 (and todo
(concat (org-export-data todo info
) " ")))))
189 (tags (and (plist-get info
:with-tags
)
190 (let ((tag-list (org-export-get-tags headline info
)))
193 (mapconcat 'identity tag-list
":"))))))
195 (and (plist-get info
:with-priority
)
196 (let ((char (org-element-property :priority headline
)))
197 (and char
(format "[#%c] " char
)))))
199 (and (plist-get info
:with-toc
)
200 (format "<a id=\"%s\"></a>"
201 (or (org-element-property :CUSTOM_ID headline
)
202 (org-export-get-reference headline info
)))))
203 ;; Headline text without tags.
204 (heading (concat todo priority title
))
205 (style (plist-get info
:md-headline-style
)))
207 ;; Cannot create a headline. Fall-back to a list.
208 ((or (org-export-low-level-p headline info
)
209 (not (memq style
'(atx setext
)))
210 (and (eq style
'atx
) (> level
6))
211 (and (eq style
'setext
) (> level
2)))
213 (if (not (org-export-numbered-headline-p headline info
)) "-"
214 (concat (number-to-string
215 (car (last (org-export-get-headline-number
218 (concat bullet
(make-string (- 4 (length bullet
)) ?\s
) heading tags
221 (replace-regexp-in-string "^" " " contents
)))))
222 ;; Use "Setext" style.
224 (concat heading tags anchor
"\n"
225 (make-string (length heading
) (if (= level
1) ?
= ?-
))
229 (t (concat (make-string level ?
#) " " heading tags anchor
"\n\n"
235 (defun org-md-horizontal-rule (_horizontal-rule _contents _info
)
236 "Transcode HORIZONTAL-RULE element into Markdown format.
237 CONTENTS is the horizontal rule contents. INFO is a plist used
238 as a communication channel."
244 (defun org-md-italic (_italic contents _info
)
245 "Transcode ITALIC object into Markdown format.
246 CONTENTS is the text within italic markup. INFO is a plist used
247 as a communication channel."
248 (format "*%s*" contents
))
253 (defun org-md-item (item contents info
)
254 "Transcode ITEM element into Markdown format.
255 CONTENTS is the item contents. INFO is a plist used as
256 a communication channel."
257 (let* ((type (org-element-property :type
(org-export-get-parent item
)))
258 (struct (org-element-property :structure item
))
259 (bullet (if (not (eq type
'ordered
)) "-"
260 (concat (number-to-string
261 (car (last (org-list-get-item-number
262 (org-element-property :begin item
)
264 (org-list-prevs-alist struct
)
265 (org-list-parents-alist struct
)))))
268 (make-string (- 4 (length bullet
)) ?
)
269 (pcase (org-element-property :checkbox item
)
273 (let ((tag (org-element-property :tag item
)))
274 (and tag
(format "**%s:** "(org-export-data tag info
))))
276 (org-trim (replace-regexp-in-string "^" " " contents
))))))
282 (defun org-md-keyword (keyword contents info
)
283 "Transcode a KEYWORD element into Markdown format.
284 CONTENTS is nil. INFO is a plist used as a communication
286 (if (member (org-element-property :key keyword
) '("MARKDOWN" "MD"))
287 (org-element-property :value keyword
)
288 (org-export-with-backend 'html keyword contents info
)))
293 (defun org-md-line-break (_line-break _contents _info
)
294 "Transcode LINE-BREAK object into Markdown format.
295 CONTENTS is nil. INFO is a plist used as a communication
302 (defun org-md-link (link contents info
)
303 "Transcode LINE-BREAK object into Markdown format.
304 CONTENTS is the link's description. INFO is a plist used as
305 a communication channel."
306 (let ((link-org-files-as-md
308 ;; Treat links to `file.org' as links to `file.md'.
309 (if (string= ".org" (downcase (file-name-extension raw-path
".")))
310 (concat (file-name-sans-extension raw-path
) ".md")
312 (type (org-element-property :type link
)))
314 ;; Link type is handled by a special function.
315 ((org-export-custom-protocol-maybe link contents
'md
))
316 ((member type
'("custom-id" "id" "fuzzy"))
317 (let ((destination (if (string= type
"fuzzy")
318 (org-export-resolve-fuzzy-link link info
)
319 (org-export-resolve-id-link link info
))))
320 (pcase (org-element-type destination
)
321 (`plain-text
; External file.
322 (let ((path (funcall link-org-files-as-md destination
)))
323 (if (not contents
) (format "<%s>" path
)
324 (format "[%s](%s)" contents path
))))
329 (cond ((org-string-nw-p contents
))
330 ((org-export-numbered-headline-p destination info
)
331 (mapconcat #'number-to-string
332 (org-export-get-headline-number destination info
)
334 (t (org-export-data (org-element-property :title destination
)
337 (or (org-element-property :CUSTOM_ID destination
)
338 (org-export-get-reference destination info
))))
341 (or (org-string-nw-p contents
)
342 (let ((number (org-export-get-ordinal destination info
)))
345 ((atom number
) (number-to-string number
))
346 (t (mapconcat #'number-to-string number
".")))))))
350 (org-export-get-reference destination info
))))))))
351 ((org-export-inline-image-p link org-html-inline-image-rules
)
352 (let ((path (let ((raw-path (org-element-property :path link
)))
353 (if (not (file-name-absolute-p raw-path
)) raw-path
354 (expand-file-name raw-path
))))
355 (caption (org-export-data
356 (org-export-get-caption
357 (org-export-get-parent-element link
)) info
)))
359 (if (not (org-string-nw-p caption
)) path
360 (format "%s \"%s\"" path caption
)))))
361 ((string= type
"coderef")
362 (let ((ref (org-element-property :path link
)))
363 (format (org-export-get-coderef-format ref contents
)
364 (org-export-resolve-coderef ref info
))))
365 ((equal type
"radio") contents
)
366 (t (let* ((raw-path (org-element-property :path link
))
369 ((member type
'("http" "https" "ftp"))
370 (concat type
":" raw-path
))
371 ((string= type
"file")
372 (org-export-file-uri (funcall link-org-files-as-md raw-path
)))
374 (if (not contents
) (format "<%s>" path
)
375 (format "[%s](%s)" contents path
)))))))
380 (defun org-md-node-property (node-property _contents _info
)
381 "Transcode a NODE-PROPERTY element into Markdown syntax.
382 CONTENTS is nil. INFO is a plist holding contextual
385 (org-element-property :key node-property
)
386 (let ((value (org-element-property :value node-property
)))
387 (if value
(concat " " value
) ""))))
392 (defun org-md-paragraph (paragraph contents _info
)
393 "Transcode PARAGRAPH element into Markdown format.
394 CONTENTS is the paragraph contents. INFO is a plist used as
395 a communication channel."
396 (let ((first-object (car (org-element-contents paragraph
))))
397 ;; If paragraph starts with a #, protect it.
398 (if (and (stringp first-object
) (string-match "\\`#" first-object
))
399 (replace-regexp-in-string "\\`#" "\\#" contents nil t
)
405 (defun org-md-plain-list (_plain-list contents _info
)
406 "Transcode PLAIN-LIST element into Markdown format.
407 CONTENTS is the plain-list contents. INFO is a plist used as
408 a communication channel."
414 (defun org-md-plain-text (text info
)
415 "Transcode a TEXT string into Markdown format.
416 TEXT is the string to transcode. INFO is a plist holding
417 contextual information."
418 (when (plist-get info
:with-smart-quotes
)
419 (setq text
(org-export-activate-smart-quotes text
:html info
)))
420 ;; Protect ambiguous #. This will protect # at the beginning of
421 ;; a line, but not at the beginning of a paragraph. See
422 ;; `org-md-paragraph'.
423 (setq text
(replace-regexp-in-string "\n#" "\n\\\\#" text
))
424 ;; Protect ambiguous !
425 (setq text
(replace-regexp-in-string "\\(!\\)\\[" "\\\\!" text nil nil
1))
426 ;; Protect `, *, _ and \
427 (setq text
(replace-regexp-in-string "[`*_\\]" "\\\\\\&" text
))
428 ;; Handle special strings, if required.
429 (when (plist-get info
:with-special-strings
)
430 (setq text
(org-html-convert-special-strings text
)))
431 ;; Handle break preservation, if required.
432 (when (plist-get info
:preserve-breaks
)
433 (setq text
(replace-regexp-in-string "[ \t]*\n" " \n" text
)))
440 (defun org-md-property-drawer (_property-drawer contents _info
)
441 "Transcode a PROPERTY-DRAWER element into Markdown format.
442 CONTENTS holds the contents of the drawer. INFO is a plist
443 holding contextual information."
444 (and (org-string-nw-p contents
)
445 (replace-regexp-in-string "^" " " contents
)))
450 (defun org-md-quote-block (_quote-block contents _info
)
451 "Transcode QUOTE-BLOCK element into Markdown format.
452 CONTENTS is the quote-block contents. INFO is a plist used as
453 a communication channel."
454 (replace-regexp-in-string
456 (replace-regexp-in-string "\n\\'" "" contents
)))
461 (defun org-md-section (_section contents _info
)
462 "Transcode SECTION element into Markdown format.
463 CONTENTS is the section contents. INFO is a plist used as
464 a communication channel."
470 (defun org-md-inner-template (contents info
)
471 "Return body of document after converting it to Markdown syntax.
472 CONTENTS is the transcoded contents string. INFO is a plist
473 holding export options."
474 ;; Make sure CONTENTS is separated from table of contents and
475 ;; footnotes with at least a blank line.
476 (org-trim (org-html-inner-template (concat "\n" contents
"\n") info
)))
478 (defun org-md-template (contents _info
)
479 "Return complete document string after Markdown conversion.
480 CONTENTS is the transcoded contents string. INFO is a plist used
481 as a communication channel."
486 ;;; Interactive function
489 (defun org-md-export-as-markdown (&optional async subtreep visible-only
)
490 "Export current buffer to a Markdown buffer.
492 If narrowing is active in the current buffer, only export its
495 If a region is active, export that region.
497 A non-nil optional argument ASYNC means the process should happen
498 asynchronously. The resulting buffer should be accessible
499 through the `org-export-stack' interface.
501 When optional argument SUBTREEP is non-nil, export the sub-tree
502 at point, extracting information from the headline properties
505 When optional argument VISIBLE-ONLY is non-nil, don't export
506 contents of hidden elements.
508 Export is done in a buffer named \"*Org MD Export*\", which will
509 be displayed when `org-export-show-temporary-export-buffer' is
512 (org-export-to-buffer 'md
"*Org MD Export*"
513 async subtreep visible-only nil nil
(lambda () (text-mode))))
516 (defun org-md-convert-region-to-md ()
517 "Assume the current region has org-mode syntax, and convert it to Markdown.
518 This can be used in any buffer. For example, you can write an
519 itemized list in org-mode syntax in a Markdown buffer and use
520 this command to convert it."
522 (org-export-replace-region-by 'md
))
526 (defun org-md-export-to-markdown (&optional async subtreep visible-only
)
527 "Export current buffer to a Markdown file.
529 If narrowing is active in the current buffer, only export its
532 If a region is active, export that region.
534 A non-nil optional argument ASYNC means the process should happen
535 asynchronously. The resulting file should be accessible through
536 the `org-export-stack' interface.
538 When optional argument SUBTREEP is non-nil, export the sub-tree
539 at point, extracting information from the headline properties
542 When optional argument VISIBLE-ONLY is non-nil, don't export
543 contents of hidden elements.
545 Return output file's name."
547 (let ((outfile (org-export-output-file-name ".md" subtreep
)))
548 (org-export-to-file 'md outfile async subtreep visible-only
)))
551 (defun org-md-publish-to-md (plist filename pub-dir
)
552 "Publish an org file to Markdown.
554 FILENAME is the filename of the Org file to be published. PLIST
555 is the property list for the given project. PUB-DIR is the
556 publishing directory.
558 Return output file name."
559 (org-publish-org-to 'md filename
".md" plist pub-dir
))
564 ;; generated-autoload-file: "org-loaddefs.el"
567 ;;; ox-md.el ends here