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