1 ;;; ox-md.el --- Markdown Back-End for Org Export Engine
3 ;; Copyright (C) 2012-2014 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
31 (eval-when-compile (require 'cl
))
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 :export-block
'("MD" "MARKDOWN")
59 :filters-alist
'((:filter-parse-tree . org-md-separate-elements
))
61 '(?m
"Export to Markdown"
62 ((?M
"To temporary buffer"
63 (lambda (a s v b
) (org-md-export-as-markdown a s v
)))
64 (?m
"To file" (lambda (a s v b
) (org-md-export-to-markdown a s v
)))
65 (?o
"To file and open"
67 (if a
(org-md-export-to-markdown t s v
)
68 (org-open-file (org-md-export-to-markdown nil s v
)))))))
69 :translate-alist
'((bold . org-md-bold
)
70 (code . org-md-verbatim
)
71 (comment .
(lambda (&rest args
) ""))
72 (comment-block .
(lambda (&rest args
) ""))
73 (example-block . org-md-example-block
)
74 (export-block . org-md-export-block
)
75 (fixed-width . org-md-example-block
)
76 (footnote-definition . ignore
)
77 (footnote-reference . ignore
)
78 (headline . org-md-headline
)
79 (horizontal-rule . org-md-horizontal-rule
)
80 (inline-src-block . org-md-verbatim
)
81 (inner-template . org-md-inner-template
)
82 (italic . org-md-italic
)
84 (keyword . org-md-keyword
)
85 (line-break . org-md-line-break
)
87 (node-property . org-md-node-property
)
88 (paragraph . org-md-paragraph
)
89 (plain-list . org-md-plain-list
)
90 (plain-text . org-md-plain-text
)
91 (property-drawer . org-md-property-drawer
)
92 (quote-block . org-md-quote-block
)
93 (section . org-md-section
)
94 (src-block . org-md-example-block
)
95 (template . org-md-template
)
96 (verbatim . org-md-verbatim
)))
101 (defun org-md-separate-elements (tree backend info
)
102 "Fix blank lines between elements.
104 TREE is the parse tree being exported. BACKEND is the export
105 back-end used. INFO is a plist used as a communication channel.
107 Make sure there's no blank line before a plain list, unless it is
108 located right after a paragraph. Otherwise, add a blank line
109 between elements. Blank lines between items are preserved.
111 Assume BACKEND is `md'."
112 (org-element-map tree
(remq 'item org-element-all-elements
)
114 (org-element-put-property
116 (if (and (eq (org-element-type (org-export-get-next-element elem info
))
118 (not (and (eq (org-element-type elem
) 'paragraph
)
119 (org-export-get-previous-element elem info
))))
122 ;; Return updated tree.
127 ;;; Transcode Functions
131 (defun org-md-bold (bold contents info
)
132 "Transcode BOLD object into Markdown format.
133 CONTENTS is the text within bold markup. INFO is a plist used as
134 a communication channel."
135 (format "**%s**" contents
))
138 ;;;; Code and Verbatim
140 (defun org-md-verbatim (verbatim contents info
)
141 "Transcode VERBATIM object into Markdown format.
142 CONTENTS is nil. INFO is a plist used as a communication
144 (let ((value (org-element-property :value verbatim
)))
145 (format (cond ((not (string-match "`" value
)) "`%s`")
146 ((or (string-match "\\``" value
)
147 (string-match "`\\'" value
))
153 ;;;; Example Block, Src Block and export Block
155 (defun org-md-example-block (example-block contents info
)
156 "Transcode EXAMPLE-BLOCK element into Markdown format.
157 CONTENTS is nil. INFO is a plist used as a communication
159 (replace-regexp-in-string
161 (org-remove-indentation
162 (org-element-property :value example-block
))))
164 (defun org-md-export-block (export-block contents info
)
165 "Transcode a EXPORT-BLOCK element from Org to Markdown.
166 CONTENTS is nil. INFO is a plist holding contextual information."
167 (if (member (org-element-property :type export-block
) '("MARKDOWN" "MD"))
168 (org-remove-indentation (org-element-property :value export-block
))
169 ;; Also include HTML export blocks.
170 (org-export-with-backend 'html export-block contents info
)))
175 (defun org-md-headline (headline contents info
)
176 "Transcode HEADLINE element into Markdown format.
177 CONTENTS is the headline contents. INFO is a plist used as
178 a communication channel."
179 (unless (org-element-property :footnote-section-p headline
)
180 (let* ((level (org-export-get-relative-level headline info
))
181 (title (org-export-data (org-element-property :title headline
) info
))
182 (todo (and (plist-get info
:with-todo-keywords
)
183 (let ((todo (org-element-property :todo-keyword
185 (and todo
(concat (org-export-data todo info
) " ")))))
186 (tags (and (plist-get info
:with-tags
)
187 (let ((tag-list (org-export-get-tags headline info
)))
190 (mapconcat 'identity tag-list
":"))))))
192 (and (plist-get info
:with-priority
)
193 (let ((char (org-element-property :priority headline
)))
194 (and char
(format "[#%c] " char
)))))
195 ;; Headline text without tags.
196 (heading (concat todo priority title
)))
198 ;; Cannot create a headline. Fall-back to a list.
199 ((or (org-export-low-level-p headline info
)
200 (not (memq org-md-headline-style
'(atx setext
)))
201 (and (eq org-md-headline-style
'atx
) (> level
6))
202 (and (eq org-md-headline-style
'setext
) (> level
2)))
204 (if (not (org-export-numbered-headline-p headline info
)) "-"
205 (concat (number-to-string
206 (car (last (org-export-get-headline-number
209 (concat bullet
(make-string (- 4 (length bullet
)) ?
) heading tags
212 (replace-regexp-in-string "^" " " contents
)))))
213 ;; Use "Setext" style.
214 ((eq org-md-headline-style
'setext
)
215 (concat heading tags
"\n"
216 (make-string (length heading
) (if (= level
1) ?
= ?-
))
220 (t (concat (make-string level ?
#) " " heading tags
"\n\n" contents
))))))
225 (defun org-md-horizontal-rule (horizontal-rule contents info
)
226 "Transcode HORIZONTAL-RULE element into Markdown format.
227 CONTENTS is the horizontal rule contents. INFO is a plist used
228 as a communication channel."
234 (defun org-md-italic (italic contents info
)
235 "Transcode ITALIC object into Markdown format.
236 CONTENTS is the text within italic markup. INFO is a plist used
237 as a communication channel."
238 (format "*%s*" contents
))
243 (defun org-md-item (item contents info
)
244 "Transcode ITEM element into Markdown format.
245 CONTENTS is the item contents. INFO is a plist used as
246 a communication channel."
247 (let* ((type (org-element-property :type
(org-export-get-parent item
)))
248 (struct (org-element-property :structure item
))
249 (bullet (if (not (eq type
'ordered
)) "-"
250 (concat (number-to-string
251 (car (last (org-list-get-item-number
252 (org-element-property :begin item
)
254 (org-list-prevs-alist struct
)
255 (org-list-parents-alist struct
)))))
258 (make-string (- 4 (length bullet
)) ?
)
259 (case (org-element-property :checkbox item
)
263 (let ((tag (org-element-property :tag item
)))
264 (and tag
(format "**%s:** "(org-export-data tag info
))))
266 (org-trim (replace-regexp-in-string "^" " " contents
))))))
272 (defun org-md-keyword (keyword contents info
)
273 "Transcode a KEYWORD element into Markdown format.
274 CONTENTS is nil. INFO is a plist used as a communication
276 (if (member (org-element-property :key keyword
) '("MARKDOWN" "MD"))
277 (org-element-property :value keyword
)
278 (org-export-with-backend 'html keyword contents info
)))
283 (defun org-md-line-break (line-break contents info
)
284 "Transcode LINE-BREAK object into Markdown format.
285 CONTENTS is nil. INFO is a plist used as a communication
292 (defun org-md-link (link contents info
)
293 "Transcode LINE-BREAK object into Markdown format.
294 CONTENTS is the link's description. INFO is a plist used as
295 a communication channel."
296 (let ((--link-org-files-as-html-maybe
298 (lambda (raw-path info
)
299 ;; Treat links to `file.org' as links to `file.html', if
300 ;; needed. See `org-html-link-org-files-as-html'.
302 ((and org-html-link-org-files-as-html
304 (downcase (file-name-extension raw-path
"."))))
305 (concat (file-name-sans-extension raw-path
) "."
306 (plist-get info
:html-extension
)))
308 (type (org-element-property :type link
)))
309 (cond ((member type
'("custom-id" "id"))
310 (let ((destination (org-export-resolve-id-link link info
)))
311 (if (stringp destination
) ; External file.
312 (let ((path (funcall --link-org-files-as-html-maybe
314 (if (not contents
) (format "<%s>" path
)
315 (format "[%s](%s)" contents path
)))
317 (and contents
(concat contents
" "))
319 (format (org-export-translate "See section %s" :html info
)
320 (mapconcat 'number-to-string
321 (org-export-get-headline-number
324 ((org-export-inline-image-p link org-html-inline-image-rules
)
325 (let ((path (let ((raw-path (org-element-property :path link
)))
326 (if (not (file-name-absolute-p raw-path
)) raw-path
327 (expand-file-name raw-path
)))))
329 (let ((caption (org-export-get-caption
330 (org-export-get-parent-element link
))))
331 (when caption
(org-export-data caption info
)))
333 ((string= type
"coderef")
334 (let ((ref (org-element-property :path link
)))
335 (format (org-export-get-coderef-format ref contents
)
336 (org-export-resolve-coderef ref info
))))
337 ((equal type
"radio")
338 (let ((destination (org-export-resolve-radio-link link info
)))
339 (org-export-data (org-element-contents destination
) info
)))
340 ((equal type
"fuzzy")
341 (let ((destination (org-export-resolve-fuzzy-link link info
)))
342 (if (org-string-nw-p contents
) contents
344 (let ((number (org-export-get-ordinal destination info
)))
346 (if (atom number
) (number-to-string number
)
347 (mapconcat 'number-to-string number
"."))))))))
348 (t (let* ((raw-path (org-element-property :path link
))
350 ((member type
'("http" "https" "ftp"))
351 (concat type
":" raw-path
))
353 ;; Treat links to ".org" files as ".html",
356 (funcall --link-org-files-as-html-maybe
358 ;; If file path is absolute, prepend it
359 ;; with protocol component - "file://".
360 (if (not (file-name-absolute-p raw-path
)) raw-path
361 (concat "file://" (expand-file-name raw-path
))))
363 (if (not contents
) (format "<%s>" path
)
364 (format "[%s](%s)" contents path
)))))))
369 (defun org-md-node-property (node-property contents info
)
370 "Transcode a NODE-PROPERTY element into Markdown syntax.
371 CONTENTS is nil. INFO is a plist holding contextual
374 (org-element-property :key node-property
)
375 (let ((value (org-element-property :value node-property
)))
376 (if value
(concat " " value
) ""))))
381 (defun org-md-paragraph (paragraph contents info
)
382 "Transcode PARAGRAPH element into Markdown format.
383 CONTENTS is the paragraph contents. INFO is a plist used as
384 a communication channel."
385 (let ((first-object (car (org-element-contents paragraph
))))
386 ;; If paragraph starts with a #, protect it.
387 (if (and (stringp first-object
) (string-match "\\`#" first-object
))
388 (replace-regexp-in-string "\\`#" "\\#" contents nil t
)
394 (defun org-md-plain-list (plain-list contents info
)
395 "Transcode PLAIN-LIST element into Markdown format.
396 CONTENTS is the plain-list contents. INFO is a plist used as
397 a communication channel."
403 (defun org-md-plain-text (text info
)
404 "Transcode a TEXT string into Markdown format.
405 TEXT is the string to transcode. INFO is a plist holding
406 contextual information."
407 (when (plist-get info
:with-smart-quotes
)
408 (setq text
(org-export-activate-smart-quotes text
:html info
)))
409 ;; Protect ambiguous #. This will protect # at the beginning of
410 ;; a line, but not at the beginning of a paragraph. See
411 ;; `org-md-paragraph'.
412 (setq text
(replace-regexp-in-string "\n#" "\n\\\\#" text
))
413 ;; Protect ambiguous !
414 (setq text
(replace-regexp-in-string "\\(!\\)\\[" "\\\\!" text nil nil
1))
415 ;; Protect `, *, _ and \
416 (setq text
(replace-regexp-in-string "[`*_\\]" "\\\\\\&" text
))
417 ;; Handle special strings, if required.
418 (when (plist-get info
:with-special-strings
)
419 (setq text
(org-html-convert-special-strings text
)))
420 ;; Handle break preservation, if required.
421 (when (plist-get info
:preserve-breaks
)
422 (setq text
(replace-regexp-in-string "[ \t]*\n" " \n" text
)))
429 (defun org-md-property-drawer (property-drawer contents info
)
430 "Transcode a PROPERTY-DRAWER element into Markdown format.
431 CONTENTS holds the contents of the drawer. INFO is a plist
432 holding contextual information."
433 (and (org-string-nw-p contents
)
434 (replace-regexp-in-string "^" " " contents
)))
439 (defun org-md-quote-block (quote-block contents info
)
440 "Transcode QUOTE-BLOCK element into Markdown format.
441 CONTENTS is the quote-block contents. INFO is a plist used as
442 a communication channel."
443 (replace-regexp-in-string
445 (replace-regexp-in-string "\n\\'" "" contents
)))
450 (defun org-md-section (section contents info
)
451 "Transcode SECTION element into Markdown format.
452 CONTENTS is the section contents. INFO is a plist used as
453 a communication channel."
459 (defun org-md-inner-template (contents info
)
460 "Return body of document after converting it to Markdown syntax.
461 CONTENTS is the transcoded contents string. INFO is a plist
462 holding export options."
463 ;; Make sure CONTENTS is separated from table of contents and
464 ;; footnotes with at least a blank line.
465 (org-trim (org-html-inner-template (concat "\n" contents
"\n") info
)))
467 (defun org-md-template (contents info
)
468 "Return complete document string after Markdown conversion.
469 CONTENTS is the transcoded contents string. INFO is a plist used
470 as a communication channel."
475 ;;; Interactive function
478 (defun org-md-export-as-markdown (&optional async subtreep visible-only
)
479 "Export current buffer to a Markdown buffer.
481 If narrowing is active in the current buffer, only export its
484 If a region is active, export that region.
486 A non-nil optional argument ASYNC means the process should happen
487 asynchronously. The resulting buffer should be accessible
488 through the `org-export-stack' interface.
490 When optional argument SUBTREEP is non-nil, export the sub-tree
491 at point, extracting information from the headline properties
494 When optional argument VISIBLE-ONLY is non-nil, don't export
495 contents of hidden elements.
497 Export is done in a buffer named \"*Org MD Export*\", which will
498 be displayed when `org-export-show-temporary-export-buffer' is
501 (org-export-to-buffer 'md
"*Org MD Export*"
502 async subtreep visible-only nil nil
(lambda () (text-mode))))
505 (defun org-md-convert-region-to-md ()
506 "Assume the current region has org-mode syntax, and convert it to Markdown.
507 This can be used in any buffer. For example, you can write an
508 itemized list in org-mode syntax in a Markdown buffer and use
509 this command to convert it."
511 (org-export-replace-region-by 'md
))
515 (defun org-md-export-to-markdown (&optional async subtreep visible-only
)
516 "Export current buffer to a Markdown file.
518 If narrowing is active in the current buffer, only export its
521 If a region is active, export that region.
523 A non-nil optional argument ASYNC means the process should happen
524 asynchronously. The resulting file should be accessible through
525 the `org-export-stack' interface.
527 When optional argument SUBTREEP is non-nil, export the sub-tree
528 at point, extracting information from the headline properties
531 When optional argument VISIBLE-ONLY is non-nil, don't export
532 contents of hidden elements.
534 Return output file's name."
536 (let ((outfile (org-export-output-file-name ".md" subtreep
)))
537 (org-export-to-file 'md outfile async subtreep visible-only
)))
540 (defun org-md-publish-to-md (plist filename pub-dir
)
541 "Publish an org file to Markdown.
543 FILENAME is the filename of the Org file to be published. PLIST
544 is the property list for the given project. PUB-DIR is the
545 publishing directory.
547 Return output file name."
548 (org-publish-org-to 'md filename
".md" plist pub-dir
))
553 ;; generated-autoload-file: "org-loaddefs.el"
556 ;;; ox-md.el ends here