org-element: Remove :alt-title property for headlines
[org-mode.git] / contrib / lisp / ox-gfm.el
blobf7acc94646f3087e9f21ba0a0879bee02f38b742
1 ;;; ox-gfm.el --- Github Flavored Markdown Back-End for Org Export Engine
3 ;; Copyright (C) 2014 Lars Tveito
5 ;; Author: Lars Tveito
6 ;; Keywords: org, wp, markdown, github
8 ;; This file is not part of GNU Emacs.
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.
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.
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/>.
23 ;;; Commentary:
25 ;; This library implements a Markdown back-end (github flavor) for Org
26 ;; exporter, based on the `md' back-end.
28 ;;; Code:
30 (require 'ox-md)
34 ;;; User-Configurable Variables
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"))
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)
51 ;;; Define Back-End
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)))
71 ;;; Transcode Functions
73 ;;;; Src Block
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)))
87 ;;;; Strike-Through
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))
95 ;;;; Table of contents
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 ")")))
108 ;;;; Template
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)))
122 ;;; Interactive function
124 ;;;###autoload
125 (defun org-gfm-export-as-markdown (&optional async subtreep visible-only)
126 "Export current buffer to a Github Flavored Markdown buffer.
128 If narrowing is active in the current buffer, only export its
129 narrowed part.
131 If a region is active, export that region.
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.
137 When optional argument SUBTREEP is non-nil, export the sub-tree
138 at point, extracting information from the headline properties
139 first.
141 When optional argument VISIBLE-ONLY is non-nil, don't export
142 contents of hidden elements.
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))))
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))
162 ;;;###autoload
163 (defun org-gfm-export-to-markdown (&optional async subtreep visible-only)
164 "Export current buffer to a Github Flavored Markdown file.
166 If narrowing is active in the current buffer, only export its
167 narrowed part.
169 If a region is active, export that region.
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.
175 When optional argument SUBTREEP is non-nil, export the sub-tree
176 at point, extracting information from the headline properties
177 first.
179 When optional argument VISIBLE-ONLY is non-nil, don't export
180 contents of hidden elements.
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)))
187 (provide 'ox-gfm)
189 ;; Local variables:
190 ;; generated-autoload-file: "org-loaddefs.el"
191 ;; End:
193 ;;; ox-gfm.el ends here