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