contrib/lisp/ox-gfm.el

   1 ;;; ox-gfm.el --- Github Flavored Markdown Back-End for Org Export Engine
   2
   3 ;; Copyright (C) 2014 Lars Tveito
   4
   5 ;; Author: Lars Tveito
   6 ;; Keywords: org, wp, markdown, github
   7
   8 ;; This file is not 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 (github flavor) for Org
  26 ;; exporter, based on the `md' back-end.
  27
  28 ;;; Code:
  29
  30 (require 'ox-md)
  31
  32
  33 \f
  34 ;;; User-Configurable Variables
  35
  36 (defgroup org-export-gfm nil
  37   "Options specific to Markdown export back-end."
  38   :tag "Org Github Flavored Markdown"
  39   :group 'org-export
  40   :version "24.4"
  41   :package-version '(Org . "8.0"))
  42
  43 (defcustom org-gfm-lang '(("emacs-lisp" . "lisp") ("elisp" . "lisp"))
  44   "Alist of languages that are not recognized by Github, to
  45   languages that are. Emacs lisp is a good example of this, where
  46   we can use lisp as a nice replacement."
  47   :group 'org-export-gfm)
  48
  49
  50 \f
  51 ;;; Define Back-End
  52
  53 (org-export-define-derived-backend 'gfm 'md
  54   :filters-alist '((:filter-parse-tree . org-md-separate-elements))
  55   :menu-entry
  56   '(?g "Export to Github Flavored Markdown"
  57        ((?G "To temporary buffer"
  58             (lambda (a s v b) (org-gfm-export-as-markdown a s v)))
  59         (?g "To file" (lambda (a s v b) (org-gfm-export-to-markdown a s v)))
  60         (?o "To file and open"
  61             (lambda (a s v b)
  62               (if a (org-gfm-export-to-markdown t s v)
  63                 (org-open-file (org-gfm-export-to-markdown nil s v)))))))
  64   :translate-alist '((inner-template . org-gfm-inner-template)
  65                      (strike-through . org-gfm-strike-through)
  66                      (src-block . org-gfm-src-block)))
  67
  68
  69 \f
  70 ;;; Transcode Functions
  71
  72 ;;;; Src Block
  73
  74 (defun org-gfm-src-block (src-block contents info)
  75   "Transcode SRC-BLOCK element into Github Flavored Markdown
  76 format. CONTENTS is nil.  INFO is a plist used as a communication
  77 channel."
  78   (let* ((lang (org-element-property :language src-block))
  79          (lang (or (assoc-default lang org-gfm-lang) lang))
  80          (code (org-export-format-code-default src-block info))
  81          (prefix (concat "```" lang "\n"))
  82          (suffix "```"))
  83     (concat prefix code suffix)))
  84
  85
  86 ;;;; Strike-Through
  87
  88 (defun org-html-strike-through (strike-through contents info)
  89   "Transcode STRIKE-THROUGH from Org to Markdown (GFM).
  90 CONTENTS is the text with strike-through markup.  INFO is a plist
  91 holding contextual information."
  92   (format "~~%s~~" contents))
  93
  94 ;;;; Table of contents
  95
  96 (defun org-gfm-format-toc (headline)
  97   "Return an appropriate table of contents entry for HEADLINE. INFO is a
  98 plist used as a communication channel."
  99   (let* ((title (org-export-data
 100                  (org-export-get-alt-title headline info) info))
 101          (level (1- (org-element-property :level headline)))
 102          (indent (concat (make-string (* level 2) ? )))
 103          (ref-str (replace-regexp-in-string " " "-" (downcase title))))
 104     (concat indent "- [" title "]" "(#" ref-str ")")))
 105
 106
 107 ;;;; Template
 108
 109 (defun org-gfm-inner-template (contents info)
 110   "Return body of document after converting it to Markdown syntax.
 111 CONTENTS is the transcoded contents string.  INFO is a plist
 112 holding export options."
 113   (let* ((depth (plist-get info :with-toc))
 114          (headlines (and depth (org-export-collect-headlines info depth)))
 115          (toc-string (or (mapconcat 'org-gfm-format-toc headlines "\n") ""))
 116          (toc-tail (if headlines "\n\n" "")))
 117     (concat toc-string toc-tail contents)))
 118
 119
 120 \f
 121 ;;; Interactive function
 122
 123 ;;;###autoload
 124 (defun org-gfm-export-as-markdown (&optional async subtreep visible-only)
 125   "Export current buffer to a Github Flavored Markdown buffer.
 126
 127 If narrowing is active in the current buffer, only export its
 128 narrowed part.
 129
 130 If a region is active, export that region.
 131
 132 A non-nil optional argument ASYNC means the process should happen
 133 asynchronously.  The resulting buffer should be accessible
 134 through the `org-export-stack' interface.
 135
 136 When optional argument SUBTREEP is non-nil, export the sub-tree
 137 at point, extracting information from the headline properties
 138 first.
 139
 140 When optional argument VISIBLE-ONLY is non-nil, don't export
 141 contents of hidden elements.
 142
 143 Export is done in a buffer named \"*Org GFM Export*\", which will
 144 be displayed when `org-export-show-temporary-export-buffer' is
 145 non-nil."
 146   (interactive)
 147   (org-export-to-buffer 'gfm "*Org GFM Export*"
 148     async subtreep visible-only nil nil (lambda () (text-mode))))
 149
 150
 151 ;;;###autoload
 152 (defun org-gfm-convert-region-to-md ()
 153   "Assume the current region has org-mode syntax, and convert it
 154 to Github Flavored Markdown.  This can be used in any buffer.
 155 For example, you can write an itemized list in org-mode syntax in
 156 a Markdown buffer and use this command to convert it."
 157   (interactive)
 158   (org-export-replace-region-by 'gfm))
 159
 160
 161 ;;;###autoload
 162 (defun org-gfm-export-to-markdown (&optional async subtreep visible-only)
 163   "Export current buffer to a Github Flavored Markdown file.
 164
 165 If narrowing is active in the current buffer, only export its
 166 narrowed part.
 167
 168 If a region is active, export that region.
 169
 170 A non-nil optional argument ASYNC means the process should happen
 171 asynchronously.  The resulting file should be accessible through
 172 the `org-export-stack' interface.
 173
 174 When optional argument SUBTREEP is non-nil, export the sub-tree
 175 at point, extracting information from the headline properties
 176 first.
 177
 178 When optional argument VISIBLE-ONLY is non-nil, don't export
 179 contents of hidden elements.
 180
 181 Return output file's name."
 182   (interactive)
 183   (let ((outfile (org-export-output-file-name ".md" subtreep)))
 184     (org-export-to-file 'gfm outfile async subtreep visible-only)))
 185
 186 (provide 'ox-gfm)
 187
 188 ;; Local variables:
 189 ;; generated-autoload-file: "org-loaddefs.el"
 190 ;; End:
 191
 192 ;;; ox-gfm.el ends here