lisp/ox-md.el

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