;;; ox-md.el --- Markdown Back-End for Org Export Engine ;; Copyright (C) 2012-2016 Free Software Foundation, Inc. ;; Author: Nicolas Goaziou ;; Keywords: org, wp, markdown ;; This file is part of GNU Emacs. ;; GNU Emacs is free software: you can redistribute it and/or modify ;; it under the terms of the GNU General Public License as published by ;; the Free Software Foundation, either version 3 of the License, or ;; (at your option) any later version. ;; GNU Emacs is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; You should have received a copy of the GNU General Public License ;; along with GNU Emacs. If not, see . ;;; Commentary: ;; This library implements a Markdown back-end (vanilla flavor) for ;; Org exporter, based on `html' back-end. See Org manual for more ;; information. ;;; Code: (eval-when-compile (require 'cl)) (require 'ox-html) (require 'ox-publish) ;;; User-Configurable Variables (defgroup org-export-md nil "Options specific to Markdown export back-end." :tag "Org Markdown" :group 'org-export :version "24.4" :package-version '(Org . "8.0")) (defcustom org-md-headline-style 'atx "Style used to format headlines. This variable can be set to either `atx' or `setext'." :group 'org-export-md :type '(choice (const :tag "Use \"atx\" style" atx) (const :tag "Use \"Setext\" style" setext))) ;;;; Footnotes (defcustom org-md-footnote-format "%s" "The format for the footnote reference. %s will be replaced by the footnote reference itself." :group 'org-export-md :type 'string) (defcustom org-md-footnote-section-title "Footnotes" "The title for the Footnotes section. Example: `Footnotes', `References', `Sources', etc." :group 'org-export-md :type 'string) ;;; Define Back-End (org-export-define-derived-backend 'md 'html :export-block '("MD" "MARKDOWN") :filters-alist '((:filter-parse-tree . org-md-separate-elements)) :menu-entry '(?m "Export to Markdown" ((?M "To temporary buffer" (lambda (a s v b) (org-md-export-as-markdown a s v))) (?m "To file" (lambda (a s v b) (org-md-export-to-markdown a s v))) (?o "To file and open" (lambda (a s v b) (if a (org-md-export-to-markdown t s v) (org-open-file (org-md-export-to-markdown nil s v))))))) :translate-alist '((bold . org-md-bold) (code . org-md-verbatim) (example-block . org-md-example-block) (export-block . org-md-export-block) (fixed-width . org-md-example-block) (headline . org-md-headline) (horizontal-rule . org-md-horizontal-rule) (inline-src-block . org-md-verbatim) (inner-template . org-md-inner-template) (italic . org-md-italic) (item . org-md-item) (keyword . org-md-keyword) (line-break . org-md-line-break) (link . org-md-link) (node-property . org-md-node-property) (paragraph . org-md-paragraph) (plain-list . org-md-plain-list) (plain-text . org-md-plain-text) (property-drawer . org-md-property-drawer) (quote-block . org-md-quote-block) (section . org-md-section) (src-block . org-md-example-block) (template . org-md-template) (verbatim . org-md-verbatim)) :options-alist '((:md-headline-style nil nil org-md-headline-style) (:md-footnote-format nil nil org-md-footnote-format) (:md-footnote-section-title nil nil org-md-footnote-section-title))) ;;; Filters (defun org-md-separate-elements (tree backend info) "Fix blank lines between elements. TREE is the parse tree being exported. BACKEND is the export back-end used. INFO is a plist used as a communication channel. Enforce a blank line between elements. There are two exceptions to this rule: 1. Preserve blank lines between sibling items in a plain list, 2. In an item, remove any blank line before the very first paragraph and the next sub-list when the latter ends the current item. Assume BACKEND is `md'." (org-element-map tree (remq 'item org-element-all-elements) (lambda (e) (org-element-put-property e :post-blank (if (and (eq (org-element-type e) 'paragraph) (eq (org-element-type (org-element-property :parent e)) 'item) (org-export-first-sibling-p e info) (let ((next (org-export-get-next-element e info))) (and (eq (org-element-type next) 'plain-list) (not (org-export-get-next-element next info))))) 0 1)))) ;; Return updated tree. tree) ;;; Transcode Functions ;;;; Bold (defun org-md-bold (bold contents info) "Transcode BOLD object into Markdown format. CONTENTS is the text within bold markup. INFO is a plist used as a communication channel." (format "**%s**" contents)) ;;;; Code and Verbatim (defun org-md-verbatim (verbatim contents info) "Transcode VERBATIM object into Markdown format. CONTENTS is nil. INFO is a plist used as a communication channel." (let ((value (org-element-property :value verbatim))) (format (cond ((not (string-match "`" value)) "`%s`") ((or (string-match "\\``" value) (string-match "`\\'" value)) "`` %s ``") (t "``%s``")) value))) ;;;; Example Block, Src Block and export Block (defun org-md-example-block (example-block contents info) "Transcode EXAMPLE-BLOCK element into Markdown format. CONTENTS is nil. INFO is a plist used as a communication channel." (replace-regexp-in-string "^" " " (org-remove-indentation (org-export-format-code-default example-block info)))) (defun org-md-export-block (export-block contents info) "Transcode a EXPORT-BLOCK element from Org to Markdown. CONTENTS is nil. INFO is a plist holding contextual information." (if (member (org-element-property :type export-block) '("MARKDOWN" "MD")) (org-remove-indentation (org-element-property :value export-block)) ;; Also include HTML export blocks. (org-export-with-backend 'html export-block contents info))) ;;;; Headline (defun org-md-headline (headline contents info) "Transcode HEADLINE element into Markdown format. CONTENTS is the headline contents. INFO is a plist used as a communication channel." (unless (org-element-property :footnote-section-p headline) (let* ((level (org-export-get-relative-level headline info)) (title (org-export-data (org-element-property :title headline) info)) (todo (and (plist-get info :with-todo-keywords) (let ((todo (org-element-property :todo-keyword headline))) (and todo (concat (org-export-data todo info) " "))))) (tags (and (plist-get info :with-tags) (let ((tag-list (org-export-get-tags headline info))) (and tag-list (format " :%s:" (mapconcat 'identity tag-list ":")))))) (priority (and (plist-get info :with-priority) (let ((char (org-element-property :priority headline))) (and char (format "[#%c] " char))))) (anchor (and (plist-get info :with-toc) (format "" (or (org-element-property :CUSTOM_ID headline) (org-export-get-reference headline info))))) ;; Headline text without tags. (heading (concat todo priority title)) (style (plist-get info :md-headline-style))) (cond ;; Cannot create a headline. Fall-back to a list. ((or (org-export-low-level-p headline info) (not (memq style '(atx setext))) (and (eq style 'atx) (> level 6)) (and (eq style 'setext) (> level 2))) (let ((bullet (if (not (org-export-numbered-headline-p headline info)) "-" (concat (number-to-string (car (last (org-export-get-headline-number headline info)))) ".")))) (concat bullet (make-string (- 4 (length bullet)) ?\s) heading tags "\n\n" (and contents (replace-regexp-in-string "^" " " contents))))) ;; Use "Setext" style. ((eq style 'setext) (concat heading tags anchor "\n" (make-string (length heading) (if (= level 1) ?= ?-)) "\n\n" contents)) ;; Use "atx" style. (t (concat (make-string level ?#) " " heading tags anchor "\n\n" contents)))))) ;;;; Horizontal Rule (defun org-md-horizontal-rule (horizontal-rule contents info) "Transcode HORIZONTAL-RULE element into Markdown format. CONTENTS is the horizontal rule contents. INFO is a plist used as a communication channel." "---") ;;;; Italic (defun org-md-italic (italic contents info) "Transcode ITALIC object into Markdown format. CONTENTS is the text within italic markup. INFO is a plist used as a communication channel." (format "*%s*" contents)) ;;;; Item (defun org-md-item (item contents info) "Transcode ITEM element into Markdown format. CONTENTS is the item contents. INFO is a plist used as a communication channel." (let* ((type (org-element-property :type (org-export-get-parent item))) (struct (org-element-property :structure item)) (bullet (if (not (eq type 'ordered)) "-" (concat (number-to-string (car (last (org-list-get-item-number (org-element-property :begin item) struct (org-list-prevs-alist struct) (org-list-parents-alist struct))))) ".")))) (concat bullet (make-string (- 4 (length bullet)) ? ) (case (org-element-property :checkbox item) (on "[X] ") (trans "[-] ") (off "[ ] ")) (let ((tag (org-element-property :tag item))) (and tag (format "**%s:** "(org-export-data tag info)))) (and contents (org-trim (replace-regexp-in-string "^" " " contents)))))) ;;;; Keyword (defun org-md-keyword (keyword contents info) "Transcode a KEYWORD element into Markdown format. CONTENTS is nil. INFO is a plist used as a communication channel." (if (member (org-element-property :key keyword) '("MARKDOWN" "MD")) (org-element-property :value keyword) (org-export-with-backend 'html keyword contents info))) ;;;; Line Break (defun org-md-line-break (line-break contents info) "Transcode LINE-BREAK object into Markdown format. CONTENTS is nil. INFO is a plist used as a communication channel." " \n") ;;;; Link (defun org-md-link (link contents info) "Transcode LINE-BREAK object into Markdown format. CONTENTS is the link's description. INFO is a plist used as a communication channel." (let ((link-org-files-as-md (lambda (raw-path) ;; Treat links to `file.org' as links to `file.md'. (if (string= ".org" (downcase (file-name-extension raw-path "."))) (concat (file-name-sans-extension raw-path) ".md") raw-path))) (type (org-element-property :type link))) (cond ;; Link type is handled by a special function. ((org-export-custom-protocol-maybe link contents 'md)) ((member type '("custom-id" "id" "fuzzy")) (let ((destination (if (string= type "fuzzy") (org-export-resolve-fuzzy-link link info) (org-export-resolve-id-link link info)))) (case (org-element-type destination) (plain-text ; External file. (let ((path (funcall link-org-files-as-md destination))) (if (not contents) (format "<%s>" path) (format "[%s](%s)" contents path)))) (headline (format "[%s](#%s)" ;; Description. (cond ((org-string-nw-p contents)) ((org-export-numbered-headline-p destination info) (mapconcat #'number-to-string (org-export-get-headline-number destination info) ".")) (t (org-export-data (org-element-property :title destination) info))) ;; Reference. (or (org-element-property :CUSTOM_ID destination) (org-export-get-reference destination info)))) (t (let ((description (or (org-string-nw-p contents) (let ((number (org-export-get-ordinal destination info))) (cond ((not number) nil) ((atom number) (number-to-string number)) (t (mapconcat #'number-to-string number "."))))))) (when description (format "[%s](#%s)" description (org-export-get-reference destination info)))))))) ((org-export-inline-image-p link org-html-inline-image-rules) (let ((path (let ((raw-path (org-element-property :path link))) (if (not (file-name-absolute-p raw-path)) raw-path (expand-file-name raw-path)))) (caption (org-export-data (org-export-get-caption (org-export-get-parent-element link)) info))) (format "![img](%s)" (if (not (org-string-nw-p caption)) path (format "%s \"%s\"" path caption))))) ((string= type "coderef") (let ((ref (org-element-property :path link))) (format (org-export-get-coderef-format ref contents) (org-export-resolve-coderef ref info)))) ((equal type "radio") contents) (t (let* ((raw-path (org-element-property :path link)) (path (cond ((member type '("http" "https" "ftp")) (concat type ":" raw-path)) ((string= type "file") (org-export-file-uri (funcall link-org-files-as-md raw-path))) (t raw-path)))) (if (not contents) (format "<%s>" path) (format "[%s](%s)" contents path))))))) ;;;; Node Property (defun org-md-node-property (node-property contents info) "Transcode a NODE-PROPERTY element into Markdown syntax. CONTENTS is nil. INFO is a plist holding contextual information." (format "%s:%s" (org-element-property :key node-property) (let ((value (org-element-property :value node-property))) (if value (concat " " value) "")))) ;;;; Paragraph (defun org-md-paragraph (paragraph contents info) "Transcode PARAGRAPH element into Markdown format. CONTENTS is the paragraph contents. INFO is a plist used as a communication channel." (let ((first-object (car (org-element-contents paragraph)))) ;; If paragraph starts with a #, protect it. (if (and (stringp first-object) (string-match "\\`#" first-object)) (replace-regexp-in-string "\\`#" "\\#" contents nil t) contents))) ;;;; Plain List (defun org-md-plain-list (plain-list contents info) "Transcode PLAIN-LIST element into Markdown format. CONTENTS is the plain-list contents. INFO is a plist used as a communication channel." contents) ;;;; Plain Text (defun org-md-plain-text (text info) "Transcode a TEXT string into Markdown format. TEXT is the string to transcode. INFO is a plist holding contextual information." (when (plist-get info :with-smart-quotes) (setq text (org-export-activate-smart-quotes text :html info))) ;; Protect ambiguous #. This will protect # at the beginning of ;; a line, but not at the beginning of a paragraph. See ;; `org-md-paragraph'. (setq text (replace-regexp-in-string "\n#" "\n\\\\#" text)) ;; Protect ambiguous ! (setq text (replace-regexp-in-string "\\(!\\)\\[" "\\\\!" text nil nil 1)) ;; Protect `, *, _ and \ (setq text (replace-regexp-in-string "[`*_\\]" "\\\\\\&" text)) ;; Handle special strings, if required. (when (plist-get info :with-special-strings) (setq text (org-html-convert-special-strings text))) ;; Handle break preservation, if required. (when (plist-get info :preserve-breaks) (setq text (replace-regexp-in-string "[ \t]*\n" " \n" text))) ;; Return value. text) ;;;; Property Drawer (defun org-md-property-drawer (property-drawer contents info) "Transcode a PROPERTY-DRAWER element into Markdown format. CONTENTS holds the contents of the drawer. INFO is a plist holding contextual information." (and (org-string-nw-p contents) (replace-regexp-in-string "^" " " contents))) ;;;; Quote Block (defun org-md-quote-block (quote-block contents info) "Transcode QUOTE-BLOCK element into Markdown format. CONTENTS is the quote-block contents. INFO is a plist used as a communication channel." (replace-regexp-in-string "^" "> " (replace-regexp-in-string "\n\\'" "" contents))) ;;;; Section (defun org-md-section (section contents info) "Transcode SECTION element into Markdown format. CONTENTS is the section contents. INFO is a plist used as a communication channel." contents) ;;;; Footnotes Section Header (defun org-md-footnote-section-header (info) "Renders a template for the footnotes section header in the preferred style. INFO is used as a communication channel." (let ((style (plist-get info :md-headline-style)) (section-title (plist-get info :md-footnote-section-title))) (cond ((equal style 'atx) (format "\n%s %s\n%%s\n" "##" section-title)) ((equal style 'setext) (format "\n%s\n%s\n%%s\n" section-title (make-string (length section-title) ?-)))))) ;;;; Footnotes Section (defun org-md-footnote-section (info) "Format the footnote section as Markdown. INFO is a plist used as a communication channel." (let* ((fn-alist (org-export-collect-footnote-definitions info)) (fn-alist (loop for (n type raw) in fn-alist collect (cons n (org-trim (org-export-data raw info)))))) (when fn-alist (format (org-md-footnote-section-header info) (format "\n%s\n" (mapconcat (lambda (fn) (let ((n (car fn)) (def (cdr fn))) (format "%s %s\n" (format (plist-get info :md-footnote-format) (org-html--anchor (format "fn.%d" n) n (format " href=\"#fnr.%d\"" n) info)) def))) fn-alist "\n")))))) ;;;; Table of contents (defun org-md-format-toc (headline) "Return an appropriate table of contents entry for HEADLINE. INFO is a plist used as a communication channel." (let* ((title (org-export-data (org-export-get-alt-title headline info) info)) (level (1- (org-element-property :level headline))) (indent (concat (make-string (* level 2) ? ))) (anchor (or (org-element-property :CUSTOM_ID headline) (org-export-get-reference headline info)))) (concat indent "- [" title "]" "(#" anchor ")"))) ;;;; Template (defun org-md-inner-template (contents info) "Return body of document after converting it to Markdown syntax. CONTENTS is the transcoded contents string. INFO is a plist holding export options." ;; Make sure CONTENTS is separated from table of contents and ;; footnotes with at least a blank line. (let* ((depth (plist-get info :with-toc)) (headlines (and depth (org-export-collect-headlines info depth))) (toc-string (or (mapconcat 'org-md-format-toc headlines "\n") "")) (toc-tail (if headlines "\n\n" "")) (footnotes (org-md-footnote-section info))) (org-trim (concat toc-string toc-tail contents footnotes)))) (defun org-md-template (contents info) "Return complete document string after Markdown conversion. CONTENTS is the transcoded contents string. INFO is a plist used as a communication channel." contents) ;;; Interactive function ;;;###autoload (defun org-md-export-as-markdown (&optional async subtreep visible-only) "Export current buffer to a Markdown buffer. If narrowing is active in the current buffer, only export its narrowed part. If a region is active, export that region. A non-nil optional argument ASYNC means the process should happen asynchronously. The resulting buffer should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree at point, extracting information from the headline properties first. When optional argument VISIBLE-ONLY is non-nil, don't export contents of hidden elements. Export is done in a buffer named \"*Org MD Export*\", which will be displayed when `org-export-show-temporary-export-buffer' is non-nil." (interactive) (org-export-to-buffer 'md "*Org MD Export*" async subtreep visible-only nil nil (lambda () (text-mode)))) ;;;###autoload (defun org-md-convert-region-to-md () "Assume the current region has org-mode syntax, and convert it to Markdown. This can be used in any buffer. For example, you can write an itemized list in org-mode syntax in a Markdown buffer and use this command to convert it." (interactive) (org-export-replace-region-by 'md)) ;;;###autoload (defun org-md-export-to-markdown (&optional async subtreep visible-only) "Export current buffer to a Markdown file. If narrowing is active in the current buffer, only export its narrowed part. If a region is active, export that region. A non-nil optional argument ASYNC means the process should happen asynchronously. The resulting file should be accessible through the `org-export-stack' interface. When optional argument SUBTREEP is non-nil, export the sub-tree at point, extracting information from the headline properties first. When optional argument VISIBLE-ONLY is non-nil, don't export contents of hidden elements. Return output file's name." (interactive) (let ((outfile (org-export-output-file-name ".md" subtreep))) (org-export-to-file 'md outfile async subtreep visible-only))) ;;;###autoload (defun org-md-publish-to-md (plist filename pub-dir) "Publish an org file to Markdown. FILENAME is the filename of the Org file to be published. PLIST is the property list for the given project. PUB-DIR is the publishing directory. Return output file name." (org-publish-org-to 'md filename ".md" plist pub-dir)) (provide 'ox-md) ;; Local variables: ;; generated-autoload-file: "org-loaddefs.el" ;; End: ;;; ox-md.el ends here