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