lisp/ox-md.el

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