lisp/org/ox-md.el

   1 ;;; ox-md.el --- Markdown Back-End for Org Export Engine
   2
   3 ;; Copyright (C) 2012-2016 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
 298      ((member type '("custom-id" "id"))
 299       (let ((destination (org-export-resolve-id-link link info)))
 300         (if (stringp destination)       ; External file.
 301             (let ((path (funcall link-org-files-as-md destination)))
 302               (if (not contents) (format "<%s>" path)
 303                 (format "[%s](%s)" contents path)))
 304           (concat
 305            (and contents (concat contents " "))
 306            (format "(%s)"
 307                    (format (org-export-translate "See section %s" :html info)
 308                            (mapconcat 'number-to-string
 309                                       (org-export-get-headline-number
 310                                        destination info)
 311                                       ".")))))))
 312      ((org-export-inline-image-p link org-html-inline-image-rules)
 313       (let ((path (let ((raw-path (org-element-property :path link)))
 314                     (if (not (file-name-absolute-p raw-path)) raw-path
 315                       (expand-file-name raw-path))))
 316             (caption (org-export-data
 317                       (org-export-get-caption
 318                        (org-export-get-parent-element link)) info)))
 319         (format "![img](%s)"
 320                 (if (not (org-string-nw-p caption)) path
 321                   (format "%s \"%s\"" path caption)))))
 322      ((string= type "coderef")
 323       (let ((ref (org-element-property :path link)))
 324         (format (org-export-get-coderef-format ref contents)
 325                 (org-export-resolve-coderef ref info))))
 326      ((equal type "radio") contents)
 327      ((equal type "fuzzy")
 328       (let ((destination (org-export-resolve-fuzzy-link link info)))
 329         (if (org-string-nw-p contents) contents
 330           (when destination
 331             (let ((number (org-export-get-ordinal destination info)))
 332               (when number
 333                 (if (atom number) (number-to-string number)
 334                   (mapconcat 'number-to-string number "."))))))))
 335      ;; Link type is handled by a special function.
 336      ((let ((protocol (nth 2 (assoc type org-link-protocols))))
 337         (and (functionp protocol)
 338              (funcall protocol
 339                       (org-link-unescape (org-element-property :path link))
 340                       contents
 341                       'md))))
 342      (t (let* ((raw-path (org-element-property :path link))
 343                (path
 344                 (cond
 345                  ((member type '("http" "https" "ftp"))
 346                   (concat type ":" raw-path))
 347                  ((string= type "file")
 348                   (let ((path (funcall link-org-files-as-md raw-path)))
 349                     (if (not (file-name-absolute-p path)) path
 350                       ;; If file path is absolute, prepend it
 351                       ;; with "file:" component.
 352                       (concat "file:" path))))
 353                  (t raw-path))))
 354           (if (not contents) (format "<%s>" path)
 355             (format "[%s](%s)" contents path)))))))
 356
 357
 358 ;;;; Paragraph
 359
 360 (defun org-md-paragraph (paragraph contents info)
 361   "Transcode PARAGRAPH element into Markdown format.
 362 CONTENTS is the paragraph contents.  INFO is a plist used as
 363 a communication channel."
 364   (let ((first-object (car (org-element-contents paragraph))))
 365     ;; If paragraph starts with a #, protect it.
 366     (if (and (stringp first-object) (string-match "\\`#" first-object))
 367         (replace-regexp-in-string "\\`#" "\\#" contents nil t)
 368       contents)))
 369
 370
 371 ;;;; Plain List
 372
 373 (defun org-md-plain-list (plain-list contents info)
 374   "Transcode PLAIN-LIST element into Markdown format.
 375 CONTENTS is the plain-list contents.  INFO is a plist used as
 376 a communication channel."
 377   contents)
 378
 379
 380 ;;;; Plain Text
 381
 382 (defun org-md-plain-text (text info)
 383   "Transcode a TEXT string into Markdown format.
 384 TEXT is the string to transcode.  INFO is a plist holding
 385 contextual information."
 386   (when (plist-get info :with-smart-quotes)
 387     (setq text (org-export-activate-smart-quotes text :html info)))
 388   ;; Protect ambiguous #.  This will protect # at the beginning of
 389   ;; a line, but not at the beginning of a paragraph.  See
 390   ;; `org-md-paragraph'.
 391   (setq text (replace-regexp-in-string "\n#" "\n\\\\#" text))
 392   ;; Protect ambiguous !
 393   (setq text (replace-regexp-in-string "\\(!\\)\\[" "\\\\!" text nil nil 1))
 394   ;; Protect `, *, _ and \
 395   (setq text (replace-regexp-in-string "[`*_\\]" "\\\\\\&" text))
 396   ;; Handle special strings, if required.
 397   (when (plist-get info :with-special-strings)
 398     (setq text (org-html-convert-special-strings text)))
 399   ;; Handle break preservation, if required.
 400   (when (plist-get info :preserve-breaks)
 401     (setq text (replace-regexp-in-string "[ \t]*\n" "  \n" text)))
 402   ;; Return value.
 403   text)
 404
 405
 406 ;;;; Quote Block
 407
 408 (defun org-md-quote-block (quote-block contents info)
 409   "Transcode QUOTE-BLOCK element into Markdown format.
 410 CONTENTS is the quote-block contents.  INFO is a plist used as
 411 a communication channel."
 412   (replace-regexp-in-string
 413    "^" "> "
 414    (replace-regexp-in-string "\n\\'" "" contents)))
 415
 416
 417 ;;;; Section
 418
 419 (defun org-md-section (section contents info)
 420   "Transcode SECTION element into Markdown format.
 421 CONTENTS is the section contents.  INFO is a plist used as
 422 a communication channel."
 423   contents)
 424
 425
 426 ;;;; Template
 427
 428 (defun org-md-inner-template (contents info)
 429   "Return body of document after converting it to Markdown syntax.
 430 CONTENTS is the transcoded contents string.  INFO is a plist
 431 holding export options."
 432   ;; Make sure CONTENTS is separated from table of contents and
 433   ;; footnotes with at least a blank line.
 434   (org-trim (org-html-inner-template (concat "\n" contents "\n") info)))
 435
 436 (defun org-md-template (contents info)
 437   "Return complete document string after Markdown conversion.
 438 CONTENTS is the transcoded contents string.  INFO is a plist used
 439 as a communication channel."
 440   contents)
 441
 442
 443 \f
 444 ;;; Interactive function
 445
 446 ;;;###autoload
 447 (defun org-md-export-as-markdown (&optional async subtreep visible-only)
 448   "Export current buffer to a Markdown buffer.
 449
 450 If narrowing is active in the current buffer, only export its
 451 narrowed part.
 452
 453 If a region is active, export that region.
 454
 455 A non-nil optional argument ASYNC means the process should happen
 456 asynchronously.  The resulting buffer should be accessible
 457 through the `org-export-stack' interface.
 458
 459 When optional argument SUBTREEP is non-nil, export the sub-tree
 460 at point, extracting information from the headline properties
 461 first.
 462
 463 When optional argument VISIBLE-ONLY is non-nil, don't export
 464 contents of hidden elements.
 465
 466 Export is done in a buffer named \"*Org MD Export*\", which will
 467 be displayed when `org-export-show-temporary-export-buffer' is
 468 non-nil."
 469   (interactive)
 470   (org-export-to-buffer 'md "*Org MD Export*"
 471     async subtreep visible-only nil nil (lambda () (text-mode))))
 472
 473 ;;;###autoload
 474 (defun org-md-convert-region-to-md ()
 475   "Assume the current region has org-mode syntax, and convert it to Markdown.
 476 This can be used in any buffer.  For example, you can write an
 477 itemized list in org-mode syntax in a Markdown buffer and use
 478 this command to convert it."
 479   (interactive)
 480   (org-export-replace-region-by 'md))
 481
 482
 483 ;;;###autoload
 484 (defun org-md-export-to-markdown (&optional async subtreep visible-only)
 485   "Export current buffer to a Markdown file.
 486
 487 If narrowing is active in the current buffer, only export its
 488 narrowed part.
 489
 490 If a region is active, export that region.
 491
 492 A non-nil optional argument ASYNC means the process should happen
 493 asynchronously.  The resulting file should be accessible through
 494 the `org-export-stack' interface.
 495
 496 When optional argument SUBTREEP is non-nil, export the sub-tree
 497 at point, extracting information from the headline properties
 498 first.
 499
 500 When optional argument VISIBLE-ONLY is non-nil, don't export
 501 contents of hidden elements.
 502
 503 Return output file's name."
 504   (interactive)
 505   (let ((outfile (org-export-output-file-name ".md" subtreep)))
 506     (org-export-to-file 'md outfile async subtreep visible-only)))
 507
 508
 509 (provide 'ox-md)
 510
 511 ;; Local variables:
 512 ;; generated-autoload-file: "org-loaddefs.el"
 513 ;; End:
 514
 515 ;;; ox-md.el ends here