Backport commit ec90220 from Emacs
[org-mode.git] / lisp / ox-html.el
blob32ec5205cf7afdd9bfc777002438b29ad5892198
1 ;;; ox-html.el --- HTML Back-End for Org Export Engine
3 ;; Copyright (C) 2011-2016 Free Software Foundation, Inc.
5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
6 ;; Jambunathan K <kjambunathan at gmail dot com>
7 ;; Keywords: outlines, hypermedia, calendar, wp
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
24 ;;; Commentary:
26 ;; This library implements a HTML back-end for Org generic exporter.
27 ;; See Org manual for more information.
29 ;;; Code:
31 ;;; Dependencies
33 (require 'ox)
34 (require 'ox-publish)
35 (require 'format-spec)
36 (eval-when-compile (require 'cl) (require 'table nil 'noerror))
39 ;;; Function Declarations
41 (declare-function org-id-find-id-file "org-id" (id))
42 (declare-function htmlize-region "ext:htmlize" (beg end))
43 (declare-function org-pop-to-buffer-same-window
44 "org-compat" (&optional buffer-or-name norecord label))
45 (declare-function mm-url-decode-entities "mm-url" ())
47 ;;; Define Back-End
49 (org-export-define-backend 'html
50 '((bold . org-html-bold)
51 (center-block . org-html-center-block)
52 (clock . org-html-clock)
53 (code . org-html-code)
54 (drawer . org-html-drawer)
55 (dynamic-block . org-html-dynamic-block)
56 (entity . org-html-entity)
57 (example-block . org-html-example-block)
58 (export-block . org-html-export-block)
59 (export-snippet . org-html-export-snippet)
60 (fixed-width . org-html-fixed-width)
61 (footnote-definition . org-html-footnote-definition)
62 (footnote-reference . org-html-footnote-reference)
63 (headline . org-html-headline)
64 (horizontal-rule . org-html-horizontal-rule)
65 (inline-src-block . org-html-inline-src-block)
66 (inlinetask . org-html-inlinetask)
67 (inner-template . org-html-inner-template)
68 (italic . org-html-italic)
69 (item . org-html-item)
70 (keyword . org-html-keyword)
71 (latex-environment . org-html-latex-environment)
72 (latex-fragment . org-html-latex-fragment)
73 (line-break . org-html-line-break)
74 (link . org-html-link)
75 (node-property . org-html-node-property)
76 (paragraph . org-html-paragraph)
77 (plain-list . org-html-plain-list)
78 (plain-text . org-html-plain-text)
79 (planning . org-html-planning)
80 (property-drawer . org-html-property-drawer)
81 (quote-block . org-html-quote-block)
82 (radio-target . org-html-radio-target)
83 (section . org-html-section)
84 (special-block . org-html-special-block)
85 (src-block . org-html-src-block)
86 (statistics-cookie . org-html-statistics-cookie)
87 (strike-through . org-html-strike-through)
88 (subscript . org-html-subscript)
89 (superscript . org-html-superscript)
90 (table . org-html-table)
91 (table-cell . org-html-table-cell)
92 (table-row . org-html-table-row)
93 (target . org-html-target)
94 (template . org-html-template)
95 (timestamp . org-html-timestamp)
96 (underline . org-html-underline)
97 (verbatim . org-html-verbatim)
98 (verse-block . org-html-verse-block))
99 :export-block "HTML"
100 :filters-alist '((:filter-options . org-html-infojs-install-script)
101 (:filter-final-output . org-html-final-function))
102 :menu-entry
103 '(?h "Export to HTML"
104 ((?H "As HTML buffer" org-html-export-as-html)
105 (?h "As HTML file" org-html-export-to-html)
106 (?o "As HTML file and open"
107 (lambda (a s v b)
108 (if a (org-html-export-to-html t s v b)
109 (org-open-file (org-html-export-to-html nil s v b)))))))
110 :options-alist
111 '((:html-doctype "HTML_DOCTYPE" nil org-html-doctype)
112 (:html-container "HTML_CONTAINER" nil org-html-container-element)
113 (:description "DESCRIPTION" nil nil newline)
114 (:keywords "KEYWORDS" nil nil space)
115 (:html-html5-fancy nil "html5-fancy" org-html-html5-fancy)
116 (:html-link-use-abs-url nil "html-link-use-abs-url" org-html-link-use-abs-url)
117 (:html-link-home "HTML_LINK_HOME" nil org-html-link-home)
118 (:html-link-up "HTML_LINK_UP" nil org-html-link-up)
119 (:html-mathjax "HTML_MATHJAX" nil "" space)
120 (:html-link-use-abs-url nil "html-link-use-abs-url" org-html-link-use-abs-url)
121 (:html-postamble nil "html-postamble" org-html-postamble)
122 (:html-preamble nil "html-preamble" org-html-preamble)
123 (:html-head "HTML_HEAD" nil org-html-head newline)
124 (:html-head-extra "HTML_HEAD_EXTRA" nil org-html-head-extra newline)
125 (:subtitle "SUBTITLE" nil nil parse)
126 (:html-head-include-default-style
127 nil "html-style" org-html-head-include-default-style)
128 (:html-head-include-scripts nil "html-scripts" org-html-head-include-scripts)
129 (:html-allow-name-attribute-in-anchors
130 nil nil org-html-allow-name-attribute-in-anchors)
131 (:html-divs nil nil org-html-divs)
132 (:html-checkbox-type nil nil org-html-checkbox-type)
133 (:html-extension nil nil org-html-extension)
134 (:html-footnote-format nil nil org-html-footnote-format)
135 (:html-footnote-separator nil nil org-html-footnote-separator)
136 (:html-footnotes-section nil nil org-html-footnotes-section)
137 (:html-format-drawer-function nil nil org-html-format-drawer-function)
138 (:html-format-headline-function nil nil org-html-format-headline-function)
139 (:html-format-inlinetask-function
140 nil nil org-html-format-inlinetask-function)
141 (:html-home/up-format nil nil org-html-home/up-format)
142 (:html-indent nil nil org-html-indent)
143 (:html-infojs-options nil nil org-html-infojs-options)
144 (:html-infojs-template nil nil org-html-infojs-template)
145 (:html-inline-image-rules nil nil org-html-inline-image-rules)
146 (:html-link-org-files-as-html nil nil org-html-link-org-files-as-html)
147 (:html-mathjax-options nil nil org-html-mathjax-options)
148 (:html-mathjax-template nil nil org-html-mathjax-template)
149 (:html-metadata-timestamp-format nil nil org-html-metadata-timestamp-format)
150 (:html-postamble-format nil nil org-html-postamble-format)
151 (:html-preamble-format nil nil org-html-preamble-format)
152 (:html-table-align-individual-fields
153 nil nil org-html-table-align-individual-fields)
154 (:html-table-caption-above nil nil org-html-table-caption-above)
155 (:html-table-data-tags nil nil org-html-table-data-tags)
156 (:html-table-header-tags nil nil org-html-table-header-tags)
157 (:html-table-use-header-tags-for-first-column
158 nil nil org-html-table-use-header-tags-for-first-column)
159 (:html-tag-class-prefix nil nil org-html-tag-class-prefix)
160 (:html-text-markup-alist nil nil org-html-text-markup-alist)
161 (:html-todo-kwd-class-prefix nil nil org-html-todo-kwd-class-prefix)
162 (:html-toplevel-hlevel nil nil org-html-toplevel-hlevel)
163 (:html-use-infojs nil nil org-html-use-infojs)
164 (:html-validation-link nil nil org-html-validation-link)
165 (:html-viewport nil nil org-html-viewport)
166 (:html-inline-images nil nil org-html-inline-images)
167 (:html-table-attributes nil nil org-html-table-default-attributes)
168 (:html-table-row-tags nil nil org-html-table-row-tags)
169 (:html-xml-declaration nil nil org-html-xml-declaration)
170 (:infojs-opt "INFOJS_OPT" nil nil)
171 ;; Redefine regular options.
172 (:creator "CREATOR" nil org-html-creator-string)
173 (:with-latex nil "tex" org-html-with-latex)
174 ;; Retrieve LaTeX header for fragments.
175 (:latex-header "LATEX_HEADER" nil nil newline)))
178 ;;; Internal Variables
180 (defvar org-html-format-table-no-css)
181 (defvar htmlize-buffer-places) ; from htmlize.el
183 (defvar org-html--pre/postamble-class "status"
184 "CSS class used for pre/postamble")
186 (defconst org-html-doctype-alist
187 '(("html4-strict" . "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"
188 \"http://www.w3.org/TR/html4/strict.dtd\">")
189 ("html4-transitional" . "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01 Transitional//EN\"
190 \"http://www.w3.org/TR/html4/loose.dtd\">")
191 ("html4-frameset" . "<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01 Frameset//EN\"
192 \"http://www.w3.org/TR/html4/frameset.dtd\">")
194 ("xhtml-strict" . "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\"
195 \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd\">")
196 ("xhtml-transitional" . "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"
197 \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">")
198 ("xhtml-frameset" . "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Frameset//EN\"
199 \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd\">")
200 ("xhtml-11" . "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.1//EN\"
201 \"http://www.w3.org/TR/xhtml1/DTD/xhtml11.dtd\">")
203 ("html5" . "<!DOCTYPE html>")
204 ("xhtml5" . "<!DOCTYPE html>"))
205 "An alist mapping (x)html flavors to specific doctypes.")
207 (defconst org-html-html5-elements
208 '("article" "aside" "audio" "canvas" "details" "figcaption"
209 "figure" "footer" "header" "menu" "meter" "nav" "output"
210 "progress" "section" "video")
211 "New elements in html5.
213 For blocks that should contain headlines, use the HTML_CONTAINER
214 property on the headline itself.")
216 (defconst org-html-special-string-regexps
217 '(("\\\\-" . "&#x00ad;") ; shy
218 ("---\\([^-]\\)" . "&#x2014;\\1") ; mdash
219 ("--\\([^-]\\)" . "&#x2013;\\1") ; ndash
220 ("\\.\\.\\." . "&#x2026;")) ; hellip
221 "Regular expressions for special string conversion.")
223 (defconst org-html-scripts
224 "<script type=\"text/javascript\">
226 @licstart The following is the entire license notice for the
227 JavaScript code in this tag.
229 Copyright (C) 2012-2013 Free Software Foundation, Inc.
231 The JavaScript code in this tag is free software: you can
232 redistribute it and/or modify it under the terms of the GNU
233 General Public License (GNU GPL) as published by the Free Software
234 Foundation, either version 3 of the License, or (at your option)
235 any later version. The code is distributed WITHOUT ANY WARRANTY;
236 without even the implied warranty of MERCHANTABILITY or FITNESS
237 FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
239 As additional permission under GNU GPL version 3 section 7, you
240 may distribute non-source (e.g., minimized or compacted) forms of
241 that code without the copy of the GNU GPL normally required by
242 section 4, provided you include this license notice and a URL
243 through which recipients can access the Corresponding Source.
246 @licend The above is the entire license notice
247 for the JavaScript code in this tag.
249 <!--/*--><![CDATA[/*><!--*/
250 function CodeHighlightOn(elem, id)
252 var target = document.getElementById(id);
253 if(null != target) {
254 elem.cacheClassElem = elem.className;
255 elem.cacheClassTarget = target.className;
256 target.className = \"code-highlighted\";
257 elem.className = \"code-highlighted\";
260 function CodeHighlightOff(elem, id)
262 var target = document.getElementById(id);
263 if(elem.cacheClassElem)
264 elem.className = elem.cacheClassElem;
265 if(elem.cacheClassTarget)
266 target.className = elem.cacheClassTarget;
268 /*]]>*///-->
269 </script>"
270 "Basic JavaScript that is needed by HTML files produced by Org mode.")
272 (defconst org-html-style-default
273 "<style type=\"text/css\">
274 <!--/*--><![CDATA[/*><!--*/
275 .title { text-align: center;
276 margin-bottom: .2em; }
277 .subtitle { text-align: center;
278 font-size: medium;
279 font-weight: bold;
280 margin-top:0; }
281 .todo { font-family: monospace; color: red; }
282 .done { font-family: monospace; color: green; }
283 .priority { font-family: monospace; color: orange; }
284 .tag { background-color: #eee; font-family: monospace;
285 padding: 2px; font-size: 80%; font-weight: normal; }
286 .timestamp { color: #bebebe; }
287 .timestamp-kwd { color: #5f9ea0; }
288 .org-right { margin-left: auto; margin-right: 0px; text-align: right; }
289 .org-left { margin-left: 0px; margin-right: auto; text-align: left; }
290 .org-center { margin-left: auto; margin-right: auto; text-align: center; }
291 .underline { text-decoration: underline; }
292 #postamble p, #preamble p { font-size: 90%; margin: .2em; }
293 p.verse { margin-left: 3%; }
294 pre {
295 border: 1px solid #ccc;
296 box-shadow: 3px 3px 3px #eee;
297 padding: 8pt;
298 font-family: monospace;
299 overflow: auto;
300 margin: 1.2em;
302 pre.src {
303 position: relative;
304 overflow: visible;
305 padding-top: 1.2em;
307 pre.src:before {
308 display: none;
309 position: absolute;
310 background-color: white;
311 top: -10px;
312 right: 10px;
313 padding: 3px;
314 border: 1px solid black;
316 pre.src:hover:before { display: inline;}
317 pre.src-sh:before { content: 'sh'; }
318 pre.src-bash:before { content: 'sh'; }
319 pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
320 pre.src-R:before { content: 'R'; }
321 pre.src-perl:before { content: 'Perl'; }
322 pre.src-java:before { content: 'Java'; }
323 pre.src-sql:before { content: 'SQL'; }
325 table { border-collapse:collapse; }
326 caption.t-above { caption-side: top; }
327 caption.t-bottom { caption-side: bottom; }
328 td, th { vertical-align:top; }
329 th.org-right { text-align: center; }
330 th.org-left { text-align: center; }
331 th.org-center { text-align: center; }
332 td.org-right { text-align: right; }
333 td.org-left { text-align: left; }
334 td.org-center { text-align: center; }
335 dt { font-weight: bold; }
336 .footpara { display: inline; }
337 .footdef { margin-bottom: 1em; }
338 .figure { padding: 1em; }
339 .figure p { text-align: center; }
340 .inlinetask {
341 padding: 10px;
342 border: 2px solid gray;
343 margin: 10px;
344 background: #ffffcc;
346 #org-div-home-and-up
347 { text-align: right; font-size: 70%; white-space: nowrap; }
348 textarea { overflow-x: auto; }
349 .linenr { font-size: smaller }
350 .code-highlighted { background-color: #ffff00; }
351 .org-info-js_info-navigation { border-style: none; }
352 #org-info-js_console-label
353 { font-size: 10px; font-weight: bold; white-space: nowrap; }
354 .org-info-js_search-highlight
355 { background-color: #ffff00; color: #000000; font-weight: bold; }
356 /*]]>*/-->
357 </style>"
358 "The default style specification for exported HTML files.
359 You can use `org-html-head' and `org-html-head-extra' to add to
360 this style. If you don't want to include this default style,
361 customize `org-html-head-include-default-style'.")
364 ;;; User Configuration Variables
366 (defgroup org-export-html nil
367 "Options for exporting Org mode files to HTML."
368 :tag "Org Export HTML"
369 :group 'org-export)
371 ;;;; Handle infojs
373 (defvar org-html-infojs-opts-table
374 '((path PATH "http://orgmode.org/org-info.js")
375 (view VIEW "info")
376 (toc TOC :with-toc)
377 (ftoc FIXED_TOC "0")
378 (tdepth TOC_DEPTH "max")
379 (sdepth SECTION_DEPTH "max")
380 (mouse MOUSE_HINT "underline")
381 (buttons VIEW_BUTTONS "0")
382 (ltoc LOCAL_TOC "1")
383 (up LINK_UP :html-link-up)
384 (home LINK_HOME :html-link-home))
385 "JavaScript options, long form for script, default values.")
387 (defcustom org-html-use-infojs 'when-configured
388 "Non-nil when Sebastian Rose's Java Script org-info.js should be active.
389 This option can be nil or t to never or always use the script.
390 It can also be the symbol `when-configured', meaning that the
391 script will be linked into the export file if and only if there
392 is a \"#+INFOJS_OPT:\" line in the buffer. See also the variable
393 `org-html-infojs-options'."
394 :group 'org-export-html
395 :version "24.4"
396 :package-version '(Org . "8.0")
397 :type '(choice
398 (const :tag "Never" nil)
399 (const :tag "When configured in buffer" when-configured)
400 (const :tag "Always" t)))
402 (defcustom org-html-infojs-options
403 (mapcar (lambda (x) (cons (car x) (nth 2 x))) org-html-infojs-opts-table)
404 "Options settings for the INFOJS JavaScript.
405 Each of the options must have an entry in `org-html-infojs-opts-table'.
406 The value can either be a string that will be passed to the script, or
407 a property. This property is then assumed to be a property that is defined
408 by the Export/Publishing setup of Org.
409 The `sdepth' and `tdepth' parameters can also be set to \"max\", which
410 means to use the maximum value consistent with other options."
411 :group 'org-export-html
412 :version "24.4"
413 :package-version '(Org . "8.0")
414 :type
415 `(set :greedy t :inline t
416 ,@(mapcar
417 (lambda (x)
418 (list 'cons (list 'const (car x))
419 '(choice
420 (symbol :tag "Publishing/Export property")
421 (string :tag "Value"))))
422 org-html-infojs-opts-table)))
424 (defcustom org-html-infojs-template
425 "<script type=\"text/javascript\" src=\"%SCRIPT_PATH\">
428 * @source: %SCRIPT_PATH
430 * @licstart The following is the entire license notice for the
431 * JavaScript code in %SCRIPT_PATH.
433 * Copyright (C) 2012-2013 Free Software Foundation, Inc.
436 * The JavaScript code in this tag is free software: you can
437 * redistribute it and/or modify it under the terms of the GNU
438 * General Public License (GNU GPL) as published by the Free Software
439 * Foundation, either version 3 of the License, or (at your option)
440 * any later version. The code is distributed WITHOUT ANY WARRANTY;
441 * without even the implied warranty of MERCHANTABILITY or FITNESS
442 * FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
444 * As additional permission under GNU GPL version 3 section 7, you
445 * may distribute non-source (e.g., minimized or compacted) forms of
446 * that code without the copy of the GNU GPL normally required by
447 * section 4, provided you include this license notice and a URL
448 * through which recipients can access the Corresponding Source.
450 * @licend The above is the entire license notice
451 * for the JavaScript code in %SCRIPT_PATH.
454 </script>
456 <script type=\"text/javascript\">
459 @licstart The following is the entire license notice for the
460 JavaScript code in this tag.
462 Copyright (C) 2012-2013 Free Software Foundation, Inc.
464 The JavaScript code in this tag is free software: you can
465 redistribute it and/or modify it under the terms of the GNU
466 General Public License (GNU GPL) as published by the Free Software
467 Foundation, either version 3 of the License, or (at your option)
468 any later version. The code is distributed WITHOUT ANY WARRANTY;
469 without even the implied warranty of MERCHANTABILITY or FITNESS
470 FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
472 As additional permission under GNU GPL version 3 section 7, you
473 may distribute non-source (e.g., minimized or compacted) forms of
474 that code without the copy of the GNU GPL normally required by
475 section 4, provided you include this license notice and a URL
476 through which recipients can access the Corresponding Source.
479 @licend The above is the entire license notice
480 for the JavaScript code in this tag.
483 <!--/*--><![CDATA[/*><!--*/
484 %MANAGER_OPTIONS
485 org_html_manager.setup(); // activate after the parameters are set
486 /*]]>*///-->
487 </script>"
488 "The template for the export style additions when org-info.js is used.
489 Option settings will replace the %MANAGER-OPTIONS cookie."
490 :group 'org-export-html
491 :version "24.4"
492 :package-version '(Org . "8.0")
493 :type 'string)
495 (defun org-html-infojs-install-script (exp-plist backend)
496 "Install script in export options when appropriate.
497 EXP-PLIST is a plist containing export options. BACKEND is the
498 export back-end currently used."
499 (unless (or (memq 'body-only (plist-get exp-plist :export-options))
500 (not (plist-get exp-plist :html-use-infojs))
501 (and (eq (plist-get exp-plist :html-use-infojs) 'when-configured)
502 (let ((opt (plist-get exp-plist :infojs-opt)))
503 (or (not opt)
504 (string= "" opt)
505 (string-match "\\<view:nil\\>" opt)))))
506 (let* ((template (plist-get exp-plist :html-infojs-template))
507 (ptoc (plist-get exp-plist :with-toc))
508 (hlevels (plist-get exp-plist :headline-levels))
509 (sdepth hlevels)
510 (tdepth (if (integerp ptoc) (min ptoc hlevels) hlevels))
511 (options (plist-get exp-plist :infojs-opt))
512 (infojs-opt (plist-get exp-plist :html-infojs-options))
513 (table org-html-infojs-opts-table)
514 style)
515 (dolist (entry table)
516 (let* ((opt (car entry))
517 (var (nth 1 entry))
518 ;; Compute default values for script option OPT from
519 ;; `org-html-infojs-options' variable.
520 (default
521 (let ((default (cdr (assq opt infojs-opt))))
522 (if (and (symbolp default) (not (memq default '(t nil))))
523 (plist-get exp-plist default)
524 default)))
525 ;; Value set through INFOJS_OPT keyword has precedence
526 ;; over the default one.
527 (val (if (and options
528 (string-match (format "\\<%s:\\(\\S-+\\)" opt)
529 options))
530 (match-string 1 options)
531 default)))
532 (case opt
533 (path (setq template
534 (replace-regexp-in-string
535 "%SCRIPT_PATH" val template t t)))
536 (sdepth (when (integerp (read val))
537 (setq sdepth (min (read val) sdepth))))
538 (tdepth (when (integerp (read val))
539 (setq tdepth (min (read val) tdepth))))
540 (otherwise (setq val
541 (cond
542 ((or (eq val t) (equal val "t")) "1")
543 ((or (eq val nil) (equal val "nil")) "0")
544 ((stringp val) val)
545 (t (format "%s" val))))
546 (push (cons var val) style)))))
547 ;; Now we set the depth of the *generated* TOC to SDEPTH,
548 ;; because the toc will actually determine the splitting. How
549 ;; much of the toc will actually be displayed is governed by the
550 ;; TDEPTH option.
551 (setq exp-plist (plist-put exp-plist :with-toc sdepth))
552 ;; The table of contents should not show more sections than we
553 ;; generate.
554 (setq tdepth (min tdepth sdepth))
555 (push (cons "TOC_DEPTH" tdepth) style)
556 ;; Build style string.
557 (setq style (mapconcat
558 (lambda (x)
559 (format "org_html_manager.set(\"%s\", \"%s\");"
560 (car x) (cdr x)))
561 style "\n"))
562 (when (and style (> (length style) 0))
563 (and (string-match "%MANAGER_OPTIONS" template)
564 (setq style (replace-match style t t template))
565 (setq exp-plist
566 (plist-put
567 exp-plist :html-head-extra
568 (concat (or (plist-get exp-plist :html-head-extra) "")
569 "\n"
570 style)))))
571 ;; This script absolutely needs the table of contents, so we
572 ;; change that setting.
573 (unless (plist-get exp-plist :with-toc)
574 (setq exp-plist (plist-put exp-plist :with-toc t)))
575 ;; Return the modified property list.
576 exp-plist)))
578 ;;;; Bold, etc.
580 (defcustom org-html-text-markup-alist
581 '((bold . "<b>%s</b>")
582 (code . "<code>%s</code>")
583 (italic . "<i>%s</i>")
584 (strike-through . "<del>%s</del>")
585 (underline . "<span class=\"underline\">%s</span>")
586 (verbatim . "<code>%s</code>"))
587 "Alist of HTML expressions to convert text markup.
589 The key must be a symbol among `bold', `code', `italic',
590 `strike-through', `underline' and `verbatim'. The value is
591 a formatting string to wrap fontified text with.
593 If no association can be found for a given markup, text will be
594 returned as-is."
595 :group 'org-export-html
596 :version "24.4"
597 :package-version '(Org . "8.0")
598 :type '(alist :key-type (symbol :tag "Markup type")
599 :value-type (string :tag "Format string"))
600 :options '(bold code italic strike-through underline verbatim))
602 (defcustom org-html-indent nil
603 "Non-nil means to indent the generated HTML.
604 Warning: non-nil may break indentation of source code blocks."
605 :group 'org-export-html
606 :version "24.4"
607 :package-version '(Org . "8.0")
608 :type 'boolean)
610 ;;;; Drawers
612 (defcustom org-html-format-drawer-function (lambda (name contents) contents)
613 "Function called to format a drawer in HTML code.
615 The function must accept two parameters:
616 NAME the drawer name, like \"LOGBOOK\"
617 CONTENTS the contents of the drawer.
619 The function should return the string to be exported.
621 For example, the variable could be set to the following function
622 in order to mimic default behavior:
624 The default value simply returns the value of CONTENTS."
625 :group 'org-export-html
626 :version "24.4"
627 :package-version '(Org . "8.0")
628 :type 'function)
630 ;;;; Footnotes
632 (defcustom org-html-footnotes-section "<div id=\"footnotes\">
633 <h2 class=\"footnotes\">%s: </h2>
634 <div id=\"text-footnotes\">
636 </div>
637 </div>"
638 "Format for the footnotes section.
639 Should contain a two instances of %s. The first will be replaced with the
640 language-specific word for \"Footnotes\", the second one will be replaced
641 by the footnotes themselves."
642 :group 'org-export-html
643 :type 'string)
645 (defcustom org-html-footnote-format "<sup>%s</sup>"
646 "The format for the footnote reference.
647 %s will be replaced by the footnote reference itself."
648 :group 'org-export-html
649 :type 'string)
651 (defcustom org-html-footnote-separator "<sup>, </sup>"
652 "Text used to separate footnotes."
653 :group 'org-export-html
654 :type 'string)
656 ;;;; Headline
658 (defcustom org-html-toplevel-hlevel 2
659 "The <H> level for level 1 headings in HTML export.
660 This is also important for the classes that will be wrapped around headlines
661 and outline structure. If this variable is 1, the top-level headlines will
662 be <h1>, and the corresponding classes will be outline-1, section-number-1,
663 and outline-text-1. If this is 2, all of these will get a 2 instead.
664 The default for this variable is 2, because we use <h1> for formatting the
665 document title."
666 :group 'org-export-html
667 :type 'integer)
669 (defcustom org-html-format-headline-function
670 'org-html-format-headline-default-function
671 "Function to format headline text.
673 This function will be called with six arguments:
674 TODO the todo keyword (string or nil).
675 TODO-TYPE the type of todo (symbol: `todo', `done', nil)
676 PRIORITY the priority of the headline (integer or nil)
677 TEXT the main headline text (string).
678 TAGS the tags (string or nil).
679 INFO the export options (plist).
681 The function result will be used in the section format string."
682 :group 'org-export-html
683 :version "25.1"
684 :package-version '(Org . "8.3")
685 :type 'function)
687 ;;;; HTML-specific
689 (defcustom org-html-allow-name-attribute-in-anchors nil
690 "When nil, do not set \"name\" attribute in anchors.
691 By default, when appropriate, anchors are formatted with \"id\"
692 but without \"name\" attribute."
693 :group 'org-export-html
694 :version "24.4"
695 :package-version '(Org . "8.0")
696 :type 'boolean)
698 ;;;; Inlinetasks
700 (defcustom org-html-format-inlinetask-function
701 'org-html-format-inlinetask-default-function
702 "Function called to format an inlinetask in HTML code.
704 The function must accept seven parameters:
705 TODO the todo keyword, as a string
706 TODO-TYPE the todo type, a symbol among `todo', `done' and nil.
707 PRIORITY the inlinetask priority, as a string
708 NAME the inlinetask name, as a string.
709 TAGS the inlinetask tags, as a list of strings.
710 CONTENTS the contents of the inlinetask, as a string.
711 INFO the export options, as a plist
713 The function should return the string to be exported."
714 :group 'org-export-html
715 :version "25.1"
716 :package-version '(Org . "8.3")
717 :type 'function)
719 ;;;; LaTeX
721 (defcustom org-html-with-latex org-export-with-latex
722 "Non-nil means process LaTeX math snippets.
724 When set, the exporter will process LaTeX environments and
725 fragments.
727 This option can also be set with the +OPTIONS line,
728 e.g. \"tex:mathjax\". Allowed values are:
730 nil Ignore math snippets.
731 `verbatim' Keep everything in verbatim
732 `dvipng' Process the LaTeX fragments to images. This will also
733 include processing of non-math environments.
734 `imagemagick' Convert the LaTeX fragments to pdf files and use
735 imagemagick to convert pdf files to png files.
736 `mathjax' Do MathJax preprocessing and arrange for MathJax.js to
737 be loaded.
738 t Synonym for `mathjax'."
739 :group 'org-export-html
740 :version "24.4"
741 :package-version '(Org . "8.0")
742 :type '(choice
743 (const :tag "Do not process math in any way" nil)
744 (const :tag "Use dvipng to make images" dvipng)
745 (const :tag "Use imagemagick to make images" imagemagick)
746 (const :tag "Use MathJax to display math" mathjax)
747 (const :tag "Leave math verbatim" verbatim)))
749 ;;;; Links :: Generic
751 (defcustom org-html-link-org-files-as-html t
752 "Non-nil means make file links to `file.org' point to `file.html'.
753 When `org-mode' is exporting an `org-mode' file to HTML, links to
754 non-html files are directly put into a href tag in HTML.
755 However, links to other Org-mode files (recognized by the
756 extension `.org') should become links to the corresponding html
757 file, assuming that the linked `org-mode' file will also be
758 converted to HTML.
759 When nil, the links still point to the plain `.org' file."
760 :group 'org-export-html
761 :type 'boolean)
763 ;;;; Links :: Inline images
765 (defcustom org-html-inline-images t
766 "Non-nil means inline images into exported HTML pages.
767 This is done using an <img> tag. When nil, an anchor with href is used to
768 link to the image."
769 :group 'org-export-html
770 :version "24.4"
771 :package-version '(Org . "8.1")
772 :type 'boolean)
774 (defcustom org-html-inline-image-rules
775 '(("file" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
776 ("http" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
777 ("https" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'"))
778 "Rules characterizing image files that can be inlined into HTML.
779 A rule consists in an association whose key is the type of link
780 to consider, and value is a regexp that will be matched against
781 link's path."
782 :group 'org-export-html
783 :version "24.4"
784 :package-version '(Org . "8.0")
785 :type '(alist :key-type (string :tag "Type")
786 :value-type (regexp :tag "Path")))
788 ;;;; Plain Text
790 (defvar org-html-protect-char-alist
791 '(("&" . "&amp;")
792 ("<" . "&lt;")
793 (">" . "&gt;"))
794 "Alist of characters to be converted by `org-html-encode-plain-text'.")
796 ;;;; Src Block
798 (defcustom org-html-htmlize-output-type 'inline-css
799 "Output type to be used by htmlize when formatting code snippets.
800 Choices are `css' to export the CSS selectors only,`inline-css'
801 to export the CSS attribute values inline in the HTML or `nil' to
802 export plain text. We use as default `inline-css', in order to
803 make the resulting HTML self-containing.
805 However, this will fail when using Emacs in batch mode for export, because
806 then no rich font definitions are in place. It will also not be good if
807 people with different Emacs setup contribute HTML files to a website,
808 because the fonts will represent the individual setups. In these cases,
809 it is much better to let Org/Htmlize assign classes only, and to use
810 a style file to define the look of these classes.
811 To get a start for your css file, start Emacs session and make sure that
812 all the faces you are interested in are defined, for example by loading files
813 in all modes you want. Then, use the command
814 \\[org-html-htmlize-generate-css] to extract class definitions."
815 :group 'org-export-html
816 :type '(choice (const css) (const inline-css) (const nil)))
818 (defcustom org-html-htmlize-font-prefix "org-"
819 "The prefix for CSS class names for htmlize font specifications."
820 :group 'org-export-html
821 :type 'string)
823 ;;;; Table
825 (defcustom org-html-table-default-attributes
826 '(:border "2" :cellspacing "0" :cellpadding "6" :rules "groups" :frame "hsides")
827 "Default attributes and values which will be used in table tags.
828 This is a plist where attributes are symbols, starting with
829 colons, and values are strings.
831 When exporting to HTML5, these values will be disregarded."
832 :group 'org-export-html
833 :version "24.4"
834 :package-version '(Org . "8.0")
835 :type '(plist :key-type (symbol :tag "Property")
836 :value-type (string :tag "Value")))
838 (defcustom org-html-table-header-tags '("<th scope=\"%s\"%s>" . "</th>")
839 "The opening and ending tags for table header fields.
840 This is customizable so that alignment options can be specified.
841 The first %s will be filled with the scope of the field, either row or col.
842 The second %s will be replaced by a style entry to align the field.
843 See also the variable `org-html-table-use-header-tags-for-first-column'.
844 See also the variable `org-html-table-align-individual-fields'."
845 :group 'org-export-html
846 :type '(cons (string :tag "Opening tag") (string :tag "Closing tag")))
848 (defcustom org-html-table-data-tags '("<td%s>" . "</td>")
849 "The opening and ending tags for table data fields.
850 This is customizable so that alignment options can be specified.
851 The first %s will be filled with the scope of the field, either row or col.
852 The second %s will be replaced by a style entry to align the field.
853 See also the variable `org-html-table-align-individual-fields'."
854 :group 'org-export-html
855 :type '(cons (string :tag "Opening tag") (string :tag "Closing tag")))
857 (defcustom org-html-table-row-tags '("<tr>" . "</tr>")
858 "The opening and ending tags for table rows.
859 This is customizable so that alignment options can be specified.
860 Instead of strings, these can be Lisp forms that will be
861 evaluated for each row in order to construct the table row tags.
863 During evaluation, these variables will be dynamically bound so that
864 you can reuse them:
866 `row-number': row number (0 is the first row)
867 `rowgroup-number': group number of current row
868 `start-rowgroup-p': non-nil means the row starts a group
869 `end-rowgroup-p': non-nil means the row ends a group
870 `top-row-p': non-nil means this is the top row
871 `bottom-row-p': non-nil means this is the bottom row
873 For example:
875 \(setq org-html-table-row-tags
876 (cons \\='(cond (top-row-p \"<tr class=\\\"tr-top\\\">\")
877 (bottom-row-p \"<tr class=\\\"tr-bottom\\\">\")
878 (t (if (= (mod row-number 2) 1)
879 \"<tr class=\\\"tr-odd\\\">\"
880 \"<tr class=\\\"tr-even\\\">\")))
881 \"</tr>\"))
883 will use the \"tr-top\" and \"tr-bottom\" classes for the top row
884 and the bottom row, and otherwise alternate between \"tr-odd\" and
885 \"tr-even\" for odd and even rows."
886 :group 'org-export-html
887 :type '(cons
888 (choice :tag "Opening tag"
889 (string :tag "Specify")
890 (sexp))
891 (choice :tag "Closing tag"
892 (string :tag "Specify")
893 (sexp))))
895 (defcustom org-html-table-align-individual-fields t
896 "Non-nil means attach style attributes for alignment to each table field.
897 When nil, alignment will only be specified in the column tags, but this
898 is ignored by some browsers (like Firefox, Safari). Opera does it right
899 though."
900 :group 'org-export-html
901 :type 'boolean)
903 (defcustom org-html-table-use-header-tags-for-first-column nil
904 "Non-nil means format column one in tables with header tags.
905 When nil, also column one will use data tags."
906 :group 'org-export-html
907 :type 'boolean)
909 (defcustom org-html-table-caption-above t
910 "When non-nil, place caption string at the beginning of the table.
911 Otherwise, place it near the end."
912 :group 'org-export-html
913 :type 'boolean)
915 ;;;; Tags
917 (defcustom org-html-tag-class-prefix ""
918 "Prefix to class names for TODO keywords.
919 Each tag gets a class given by the tag itself, with this prefix.
920 The default prefix is empty because it is nice to just use the keyword
921 as a class name. But if you get into conflicts with other, existing
922 CSS classes, then this prefix can be very useful."
923 :group 'org-export-html
924 :type 'string)
926 ;;;; Template :: Generic
928 (defcustom org-html-extension "html"
929 "The extension for exported HTML files."
930 :group 'org-export-html
931 :type 'string)
933 (defcustom org-html-xml-declaration
934 '(("html" . "<?xml version=\"1.0\" encoding=\"%s\"?>")
935 ("php" . "<?php echo \"<?xml version=\\\"1.0\\\" encoding=\\\"%s\\\" ?>\"; ?>"))
936 "The extension for exported HTML files.
937 %s will be replaced with the charset of the exported file.
938 This may be a string, or an alist with export extensions
939 and corresponding declarations.
941 This declaration only applies when exporting to XHTML."
942 :group 'org-export-html
943 :type '(choice
944 (string :tag "Single declaration")
945 (repeat :tag "Dependent on extension"
946 (cons (string :tag "Extension")
947 (string :tag "Declaration")))))
949 (defcustom org-html-coding-system 'utf-8
950 "Coding system for HTML export.
951 Use utf-8 as the default value."
952 :group 'org-export-html
953 :version "24.4"
954 :package-version '(Org . "8.0")
955 :type 'coding-system)
957 (defcustom org-html-doctype "xhtml-strict"
958 "Document type definition to use for exported HTML files.
959 Can be set with the in-buffer HTML_DOCTYPE property or for
960 publishing, with :html-doctype."
961 :group 'org-export-html
962 :version "24.4"
963 :package-version '(Org . "8.0")
964 :type (append
965 '(choice)
966 (mapcar (lambda (x) `(const ,(car x))) org-html-doctype-alist)
967 '((string :tag "Custom doctype" ))))
969 (defcustom org-html-html5-fancy nil
970 "Non-nil means using new HTML5 elements.
971 This variable is ignored for anything other than HTML5 export.
973 For compatibility with Internet Explorer, it's probably a good
974 idea to download some form of the html5shiv (for instance
975 https://code.google.com/p/html5shiv/) and add it to your
976 HTML_HEAD_EXTRA, so that your pages don't break for users of IE
977 versions 8 and below."
978 :group 'org-export-html
979 :version "24.4"
980 :package-version '(Org . "8.0")
981 :type 'boolean)
983 (defcustom org-html-container-element "div"
984 "HTML element to use for wrapping top level sections.
985 Can be set with the in-buffer HTML_CONTAINER property or for
986 publishing, with :html-container.
988 Note that changing the default will prevent you from using
989 org-info.js for your website."
990 :group 'org-export-html
991 :version "24.4"
992 :package-version '(Org . "8.0")
993 :type 'string)
995 (defcustom org-html-divs
996 '((preamble "div" "preamble")
997 (content "div" "content")
998 (postamble "div" "postamble"))
999 "Alist of the three section elements for HTML export.
1000 The car of each entry is one of `preamble', `content' or `postamble'.
1001 The cdrs of each entry are the ELEMENT_TYPE and ID for each
1002 section of the exported document.
1004 Note that changing the default will prevent you from using
1005 org-info.js for your website."
1006 :group 'org-export-html
1007 :version "24.4"
1008 :package-version '(Org . "8.0")
1009 :type '(list :greedy t
1010 (list :tag "Preamble"
1011 (const :format "" preamble)
1012 (string :tag "element") (string :tag " id"))
1013 (list :tag "Content"
1014 (const :format "" content)
1015 (string :tag "element") (string :tag " id"))
1016 (list :tag "Postamble" (const :format "" postamble)
1017 (string :tag " id") (string :tag "element"))))
1019 (defconst org-html-checkbox-types
1020 '((unicode .
1021 ((on . "&#x2611;") (off . "&#x2610;") (trans . "&#x2610;")))
1022 (ascii .
1023 ((on . "<code>[X]</code>")
1024 (off . "<code>[&#xa0;]</code>")
1025 (trans . "<code>[-]</code>")))
1026 (html .
1027 ((on . "<input type='checkbox' checked='checked' />")
1028 (off . "<input type='checkbox' />")
1029 (trans . "<input type='checkbox' />"))))
1030 "Alist of checkbox types.
1031 The cdr of each entry is an alist list three checkbox types for
1032 HTML export: `on', `off' and `trans'.
1034 The choices are:
1035 `unicode' Unicode characters (HTML entities)
1036 `ascii' ASCII characters
1037 `html' HTML checkboxes
1039 Note that only the ascii characters implement tri-state
1040 checkboxes. The other two use the `off' checkbox for `trans'.")
1042 (defcustom org-html-checkbox-type 'ascii
1043 "The type of checkboxes to use for HTML export.
1044 See `org-html-checkbox-types' for for the values used for each
1045 option."
1046 :group 'org-export-html
1047 :version "24.4"
1048 :package-version '(Org . "8.0")
1049 :type '(choice
1050 (const :tag "ASCII characters" ascii)
1051 (const :tag "Unicode characters" unicode)
1052 (const :tag "HTML checkboxes" html)))
1054 (defcustom org-html-metadata-timestamp-format "%Y-%m-%d %a %H:%M"
1055 "Format used for timestamps in preamble, postamble and metadata.
1056 See `format-time-string' for more information on its components."
1057 :group 'org-export-html
1058 :version "24.4"
1059 :package-version '(Org . "8.0")
1060 :type 'string)
1062 ;;;; Template :: Mathjax
1064 (defcustom org-html-mathjax-options
1065 '((path "http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML" )
1066 (scale "100")
1067 (align "center")
1068 (font "TeX")
1069 (linebreaks "false")
1070 (autonumber "AMS")
1071 (indent "0em")
1072 (multlinewidth "85%")
1073 (tagindent ".8em")
1074 (tagside "right"))
1075 "Options for MathJax setup.
1077 Alist of the following elements. All values are strings.
1079 path The path to MathJax.
1080 scale Scaling with HTML-CSS, MathML and SVG output engines.
1081 align How to align display math: left, center, or right.
1082 font The font to use with HTML-CSS and SVG output. As of MathJax 2.5
1083 the following values are understood: \"TeX\", \"STIX-Web\",
1084 \"Asana-Math\", \"Neo-Euler\", \"Gyre-Pagella\",
1085 \"Gyre-Termes\", and \"Latin-Modern\".
1086 linebreaks Let MathJax perform automatic linebreaks. Valid values
1087 are \"true\" and \"false\".
1088 indent If align is not center, how far from the left/right side?
1089 Valid values are \"left\" and \"right\"
1090 multlinewidth The width of the multline environment.
1091 autonumber How to number equations. Valid values are \"None\",
1092 \"all\" and \"AMS Math\".
1093 tagindent The amount tags are indented.
1094 tagside Which side to show tags/labels on. Valid values are
1095 \"left\" and \"right\"
1097 You can also customize this for each buffer, using something like
1099 #+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
1101 For further information about MathJax options, see the MathJax documentation:
1103 http://docs.mathjax.org/
1105 Please note that by using the default CDN one must agree with
1106 MathJax CDN Terms of Service.
1108 http://www.mathjax.org/mathjax-cdn-terms-of-service.html"
1109 :group 'org-export-html
1110 :package-version '(Org . "8.3")
1111 :type '(list :greedy t
1112 (list :tag "path (the path from where to load MathJax.js)"
1113 (const :format " " path) (string))
1114 (list :tag "scale (scaling for the displayed math)"
1115 (const :format " " scale) (string))
1116 (list :tag "align (alignment of displayed equations)"
1117 (const :format " " align) (string))
1118 (list :tag "font (used to display math)"
1119 (const :format " " font)
1120 (choice (const "TeX")
1121 (const "STIX-Web")
1122 (const "Asana-Math")
1123 (const "Neo-Euler")
1124 (const "Gyre-Pagella")
1125 (const "Gyre-Termes")
1126 (const "Latin-Modern")))
1127 (list :tag "linebreaks (automatic line-breaking)"
1128 (const :format " " linebreaks)
1129 (choice (const "true")
1130 (const "false")))
1131 (list :tag "autonumber (when should equations be numbered)"
1132 (const :format " " autonumber)
1133 (choice (const "AMS")
1134 (const "None")
1135 (const "All")))
1136 (list :tag "indent (indentation with left or right alignment)"
1137 (const :format " " indent) (string))
1138 (list :tag "multlinewidth (width to use for the multline environment)"
1139 (const :format " " multlinewidth) (string))
1140 (list :tag "tagindent (the indentation of tags from left or right)"
1141 (const :format " " tagindent) (string))
1142 (list :tag "tagside (location of tags)"
1143 (const :format " " tagside)
1144 (choice (const "left")
1145 (const "right")))))
1147 (defcustom org-html-mathjax-template
1148 "<script type=\"text/x-mathjax-config\">
1149 MathJax.Hub.Config({
1150 displayAlign: \"%ALIGN\",
1151 displayIndent: \"%INDENT\",
1153 \"HTML-CSS\": { scale: %SCALE,
1154 linebreaks: { automatic: \"%LINEBREAKS\" },
1155 webFont: \"%FONT\"
1157 SVG: {scale: %SCALE,
1158 linebreaks: { automatic: \"%LINEBREAKS\" },
1159 font: \"%FONT\"},
1160 NativeMML: {scale: %SCALE},
1161 TeX: { equationNumbers: {autoNumber: \"%AUTONUMBER\"},
1162 MultLineWidth: \"%MULTLINEWIDTH\",
1163 TagSide: \"%TAGSIDE\",
1164 TagIndent: \"%TAGINDENT\"
1167 </script>
1168 <script type=\"text/javascript\"
1169 src=\"%PATH\"></script>"
1170 "The MathJax template. See also `org-html-mathjax-options'."
1171 :group 'org-export-html
1172 :type 'string)
1174 ;;;; Template :: Postamble
1176 (defcustom org-html-postamble 'auto
1177 "Non-nil means insert a postamble in HTML export.
1179 When set to `auto', check against the
1180 `org-export-with-author/email/creator/date' variables to set the
1181 content of the postamble. When set to a string, use this string
1182 as the postamble. When t, insert a string as defined by the
1183 formatting string in `org-html-postamble-format'.
1185 When set to a function, apply this function and insert the
1186 returned string. The function takes the property list of export
1187 options as its only argument.
1189 Setting :html-postamble in publishing projects will take
1190 precedence over this variable."
1191 :group 'org-export-html
1192 :type '(choice (const :tag "No postamble" nil)
1193 (const :tag "Auto postamble" auto)
1194 (const :tag "Default formatting string" t)
1195 (string :tag "Custom formatting string")
1196 (function :tag "Function (must return a string)")))
1198 (defcustom org-html-postamble-format
1199 '(("en" "<p class=\"author\">Author: %a (%e)</p>
1200 <p class=\"date\">Date: %d</p>
1201 <p class=\"creator\">%c</p>
1202 <p class=\"validation\">%v</p>"))
1203 "Alist of languages and format strings for the HTML postamble.
1205 The first element of each list is the language code, as used for
1206 the LANGUAGE keyword. See `org-export-default-language'.
1208 The second element of each list is a format string to format the
1209 postamble itself. This format string can contain these elements:
1211 %t stands for the title.
1212 %s stands for the subtitle.
1213 %a stands for the author's name.
1214 %e stands for the author's email.
1215 %d stands for the date.
1216 %c will be replaced by `org-html-creator-string'.
1217 %v will be replaced by `org-html-validation-link'.
1218 %T will be replaced by the export time.
1219 %C will be replaced by the last modification time.
1221 If you need to use a \"%\" character, you need to escape it
1222 like that: \"%%\"."
1223 :group 'org-export-html
1224 :type '(repeat
1225 (list (string :tag "Language")
1226 (string :tag "Format string"))))
1228 (defcustom org-html-validation-link
1229 "<a href=\"http://validator.w3.org/check?uri=referer\">Validate</a>"
1230 "Link to HTML validation service."
1231 :group 'org-export-html
1232 :type 'string)
1234 (defcustom org-html-creator-string
1235 (format "<a href=\"http://www.gnu.org/software/emacs/\">Emacs</a> %s (<a href=\"http://orgmode.org\">Org</a> mode %s)"
1236 emacs-version
1237 (if (fboundp 'org-version) (org-version) "unknown version"))
1238 "Information about the creator of the HTML document.
1239 This option can also be set on with the CREATOR keyword."
1240 :group 'org-export-html
1241 :version "24.4"
1242 :package-version '(Org . "8.0")
1243 :type '(string :tag "Creator string"))
1245 ;;;; Template :: Preamble
1247 (defcustom org-html-preamble t
1248 "Non-nil means insert a preamble in HTML export.
1250 When t, insert a string as defined by the formatting string in
1251 `org-html-preamble-format'. When set to a string, use this
1252 formatting string instead (see `org-html-postamble-format' for an
1253 example of such a formatting string).
1255 When set to a function, apply this function and insert the
1256 returned string. The function takes the property list of export
1257 options as its only argument.
1259 Setting :html-preamble in publishing projects will take
1260 precedence over this variable."
1261 :group 'org-export-html
1262 :type '(choice (const :tag "No preamble" nil)
1263 (const :tag "Default preamble" t)
1264 (string :tag "Custom formatting string")
1265 (function :tag "Function (must return a string)")))
1267 (defcustom org-html-preamble-format '(("en" ""))
1268 "Alist of languages and format strings for the HTML preamble.
1270 The first element of each list is the language code, as used for
1271 the LANGUAGE keyword. See `org-export-default-language'.
1273 The second element of each list is a format string to format the
1274 preamble itself. This format string can contain these elements:
1276 %t stands for the title.
1277 %s stands for the subtitle.
1278 %a stands for the author's name.
1279 %e stands for the author's email.
1280 %d stands for the date.
1281 %c will be replaced by `org-html-creator-string'.
1282 %v will be replaced by `org-html-validation-link'.
1283 %T will be replaced by the export time.
1284 %C will be replaced by the last modification time.
1286 If you need to use a \"%\" character, you need to escape it
1287 like that: \"%%\".
1289 See the default value of `org-html-postamble-format' for an
1290 example."
1291 :group 'org-export-html
1292 :type '(repeat
1293 (list (string :tag "Language")
1294 (string :tag "Format string"))))
1296 (defcustom org-html-link-up ""
1297 "Where should the \"UP\" link of exported HTML pages lead?"
1298 :group 'org-export-html
1299 :type '(string :tag "File or URL"))
1301 (defcustom org-html-link-home ""
1302 "Where should the \"HOME\" link of exported HTML pages lead?"
1303 :group 'org-export-html
1304 :type '(string :tag "File or URL"))
1306 (defcustom org-html-link-use-abs-url nil
1307 "Should we prepend relative links with HTML_LINK_HOME?"
1308 :group 'org-export-html
1309 :version "24.4"
1310 :package-version '(Org . "8.1")
1311 :type 'boolean)
1313 (defcustom org-html-home/up-format
1314 "<div id=\"org-div-home-and-up\">
1315 <a accesskey=\"h\" href=\"%s\"> UP </a>
1317 <a accesskey=\"H\" href=\"%s\"> HOME </a>
1318 </div>"
1319 "Snippet used to insert the HOME and UP links.
1320 This is a format string, the first %s will receive the UP link,
1321 the second the HOME link. If both `org-html-link-up' and
1322 `org-html-link-home' are empty, the entire snippet will be
1323 ignored."
1324 :group 'org-export-html
1325 :type 'string)
1327 ;;;; Template :: Scripts
1329 (define-obsolete-variable-alias
1330 'org-html-style-include-scripts 'org-html-head-include-scripts "24.4")
1331 (defcustom org-html-head-include-scripts t
1332 "Non-nil means include the JavaScript snippets in exported HTML files.
1333 The actual script is defined in `org-html-scripts' and should
1334 not be modified."
1335 :group 'org-export-html
1336 :version "24.4"
1337 :package-version '(Org . "8.0")
1338 :type 'boolean)
1340 ;;;; Template :: Styles
1342 (define-obsolete-variable-alias
1343 'org-html-style-include-default 'org-html-head-include-default-style "24.4")
1344 (defcustom org-html-head-include-default-style t
1345 "Non-nil means include the default style in exported HTML files.
1346 The actual style is defined in `org-html-style-default' and
1347 should not be modified. Use `org-html-head' to use your own
1348 style information."
1349 :group 'org-export-html
1350 :version "24.4"
1351 :package-version '(Org . "8.0")
1352 :type 'boolean)
1353 ;;;###autoload
1354 (put 'org-html-head-include-default-style 'safe-local-variable 'booleanp)
1356 (define-obsolete-variable-alias 'org-html-style 'org-html-head "24.4")
1357 (defcustom org-html-head ""
1358 "Org-wide head definitions for exported HTML files.
1360 This variable can contain the full HTML structure to provide a
1361 style, including the surrounding HTML tags. You can consider
1362 including definitions for the following classes: title, todo,
1363 done, timestamp, timestamp-kwd, tag, target.
1365 For example, a valid value would be:
1367 <style type=\"text/css\">
1368 <![CDATA[
1369 p { font-weight: normal; color: gray; }
1370 h1 { color: black; }
1371 .title { text-align: center; }
1372 .todo, .timestamp-kwd { color: red; }
1373 .done { color: green; }
1375 </style>
1377 If you want to refer to an external style, use something like
1379 <link rel=\"stylesheet\" type=\"text/css\" href=\"mystyles.css\" />
1381 As the value of this option simply gets inserted into the HTML
1382 <head> header, you can use it to add any arbitrary text to the
1383 header.
1385 You can set this on a per-file basis using #+HTML_HEAD:,
1386 or for publication projects using the :html-head property."
1387 :group 'org-export-html
1388 :version "24.4"
1389 :package-version '(Org . "8.0")
1390 :type 'string)
1391 ;;;###autoload
1392 (put 'org-html-head 'safe-local-variable 'stringp)
1394 (defcustom org-html-head-extra ""
1395 "More head information to add in the HTML output.
1397 You can set this on a per-file basis using #+HTML_HEAD_EXTRA:,
1398 or for publication projects using the :html-head-extra property."
1399 :group 'org-export-html
1400 :version "24.4"
1401 :package-version '(Org . "8.0")
1402 :type 'string)
1403 ;;;###autoload
1404 (put 'org-html-head-extra 'safe-local-variable 'stringp)
1406 ;;;; Template :: Viewport
1408 (defcustom org-html-viewport '((width "device-width")
1409 (initial-scale "1")
1410 (minimum-scale "")
1411 (maximum-scale "")
1412 (user-scalable ""))
1413 "Viewport options for mobile-optimized sites.
1415 The following values are recognized
1417 width Size of the viewport.
1418 initial-scale Zoom level when the page is first loaded.
1419 minimum-scale Minimum allowed zoom level.
1420 maximum-scale Maximum allowed zoom level.
1421 user-scalable Whether zoom can be changed.
1423 The viewport meta tag is inserted if this variable is non-nil.
1425 See the following site for a reference:
1426 https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag"
1427 :group 'org-export-html
1428 :version "25.1"
1429 :package-version '(Org . "8.3")
1430 :type '(choice (const :tag "Disable" nil)
1431 (list :tag "Enable"
1432 (list :tag "Width of viewport"
1433 (const :format " " width)
1434 (choice (const :tag "unset" "")
1435 (string)))
1436 (list :tag "Initial scale"
1437 (const :format " " initial-scale)
1438 (choice (const :tag "unset" "")
1439 (string)))
1440 (list :tag "Minimum scale/zoom"
1441 (const :format " " minimum-scale)
1442 (choice (const :tag "unset" "")
1443 (string)))
1444 (list :tag "Maximum scale/zoom"
1445 (const :format " " maximum-scale)
1446 (choice (const :tag "unset" "")
1447 (string)))
1448 (list :tag "User scalable/zoomable"
1449 (const :format " " user-scalable)
1450 (choice (const :tag "unset" "")
1451 (const "true")
1452 (const "false"))))))
1454 ;;;; Todos
1456 (defcustom org-html-todo-kwd-class-prefix ""
1457 "Prefix to class names for TODO keywords.
1458 Each TODO keyword gets a class given by the keyword itself, with this prefix.
1459 The default prefix is empty because it is nice to just use the keyword
1460 as a class name. But if you get into conflicts with other, existing
1461 CSS classes, then this prefix can be very useful."
1462 :group 'org-export-html
1463 :type 'string)
1466 ;;; Internal Functions
1468 (defun org-html-xhtml-p (info)
1469 (let ((dt (downcase (plist-get info :html-doctype))))
1470 (string-match-p "xhtml" dt)))
1472 (defun org-html-html5-p (info)
1473 (let ((dt (downcase (plist-get info :html-doctype))))
1474 (member dt '("html5" "xhtml5" "<!doctype html>"))))
1476 (defun org-html--html5-fancy-p (info)
1477 "Non-nil when exporting to HTML5 with fancy elements.
1478 INFO is the current state of the export process, as a plist."
1479 (and (plist-get info :html-html5-fancy)
1480 (org-html-html5-p info)))
1482 (defun org-html-close-tag (tag attr info)
1483 (concat "<" tag " " attr
1484 (if (org-html-xhtml-p info) " />" ">")))
1486 (defun org-html-doctype (info)
1487 "Return correct html doctype tag from `org-html-doctype-alist',
1488 or the literal value of :html-doctype from INFO if :html-doctype
1489 is not found in the alist.
1490 INFO is a plist used as a communication channel."
1491 (let ((dt (plist-get info :html-doctype)))
1492 (or (cdr (assoc dt org-html-doctype-alist)) dt)))
1494 (defun org-html--make-attribute-string (attributes)
1495 "Return a list of attributes, as a string.
1496 ATTRIBUTES is a plist where values are either strings or nil. An
1497 attributes with a nil value will be omitted from the result."
1498 (let (output)
1499 (dolist (item attributes (mapconcat 'identity (nreverse output) " "))
1500 (cond ((null item) (pop output))
1501 ((symbolp item) (push (substring (symbol-name item) 1) output))
1502 (t (let ((key (car output))
1503 (value (replace-regexp-in-string
1504 "\"" "&quot;" (org-html-encode-plain-text item))))
1505 (setcar output (format "%s=\"%s\"" key value))))))))
1507 (defun org-html--wrap-image (contents info &optional caption label)
1508 "Wrap CONTENTS string within an appropriate environment for images.
1509 INFO is a plist used as a communication channel. When optional
1510 arguments CAPTION and LABEL are given, use them for caption and
1511 \"id\" attribute."
1512 (let ((html5-fancy (org-html--html5-fancy-p info)))
1513 (format (if html5-fancy "\n<figure%s>%s%s\n</figure>"
1514 "\n<div%s class=\"figure\">%s%s\n</div>")
1515 ;; ID.
1516 (if (org-string-nw-p label) (format " id=\"%s\"" label) "")
1517 ;; Contents.
1518 (format "\n<p>%s</p>" contents)
1519 ;; Caption.
1520 (if (not (org-string-nw-p caption)) ""
1521 (format (if html5-fancy "\n<figcaption>%s</figcaption>"
1522 "\n<p>%s</p>")
1523 caption)))))
1525 (defun org-html--format-image (source attributes info)
1526 "Return \"img\" tag with given SOURCE and ATTRIBUTES.
1527 SOURCE is a string specifying the location of the image.
1528 ATTRIBUTES is a plist, as returned by
1529 `org-export-read-attribute'. INFO is a plist used as
1530 a communication channel."
1531 (if (string= "svg" (file-name-extension source))
1532 (org-html--svg-image source attributes info)
1533 (org-html-close-tag
1534 "img"
1535 (org-html--make-attribute-string
1536 (org-combine-plists
1537 (list :src source
1538 :alt (if (string-match-p "^ltxpng/" source)
1539 (org-html-encode-plain-text
1540 (org-find-text-property-in-string 'org-latex-src source))
1541 (file-name-nondirectory source)))
1542 attributes))
1543 info)))
1545 (defun org-html--svg-image (source attributes info)
1546 "Return \"object\" appropriate for embedding svg file SOURCE
1547 with assoicated ATTRIBUTES. INFO is a plist used as a
1548 communication channel.
1550 The special attribute \"fallback\" can be used to specify a fallback
1551 image file to use if the object embedding is not supported."
1552 (let ((fallback (plist-get attributes :fallback))
1553 (attrs (org-html--make-attribute-string
1554 (plist-put attributes :fallback nil))))
1555 (format "<object type=\"image/svg+xml\" data=\"%s\" %s>\n%s</object>"
1556 source attrs
1557 (if fallback
1558 (org-html-close-tag
1559 "img" (format "src=\"%s\" %s" fallback attrs) info)
1560 "Sorry, your browser does not support SVG."))))
1562 (defun org-html--textarea-block (element)
1563 "Transcode ELEMENT into a textarea block.
1564 ELEMENT is either a src block or an example block."
1565 (let* ((code (car (org-export-unravel-code element)))
1566 (attr (org-export-read-attribute :attr_html element)))
1567 (format "<p>\n<textarea cols=\"%s\" rows=\"%s\">\n%s</textarea>\n</p>"
1568 (or (plist-get attr :width) 80)
1569 (or (plist-get attr :height) (org-count-lines code))
1570 code)))
1572 (defun org-html--has-caption-p (element &optional info)
1573 "Non-nil when ELEMENT has a caption affiliated keyword.
1574 INFO is a plist used as a communication channel. This function
1575 is meant to be used as a predicate for `org-export-get-ordinal' or
1576 a value to `org-html-standalone-image-predicate'."
1577 (org-element-property :caption element))
1579 ;;;; Table
1581 (defun org-html-htmlize-region-for-paste (beg end)
1582 "Convert the region between BEG and END to HTML, using htmlize.el.
1583 This is much like `htmlize-region-for-paste', only that it uses
1584 the settings define in the org-... variables."
1585 (let* ((htmlize-output-type org-html-htmlize-output-type)
1586 (htmlize-css-name-prefix org-html-htmlize-font-prefix)
1587 (htmlbuf (htmlize-region beg end)))
1588 (unwind-protect
1589 (with-current-buffer htmlbuf
1590 (buffer-substring (plist-get htmlize-buffer-places 'content-start)
1591 (plist-get htmlize-buffer-places 'content-end)))
1592 (kill-buffer htmlbuf))))
1594 ;;;###autoload
1595 (defun org-html-htmlize-generate-css ()
1596 "Create the CSS for all font definitions in the current Emacs session.
1597 Use this to create face definitions in your CSS style file that can then
1598 be used by code snippets transformed by htmlize.
1599 This command just produces a buffer that contains class definitions for all
1600 faces used in the current Emacs session. You can copy and paste the ones you
1601 need into your CSS file.
1603 If you then set `org-html-htmlize-output-type' to `css', calls
1604 to the function `org-html-htmlize-region-for-paste' will
1605 produce code that uses these same face definitions."
1606 (interactive)
1607 (require 'htmlize)
1608 (and (get-buffer "*html*") (kill-buffer "*html*"))
1609 (with-temp-buffer
1610 (let ((fl (face-list))
1611 (htmlize-css-name-prefix "org-")
1612 (htmlize-output-type 'css)
1613 f i)
1614 (while (setq f (pop fl)
1615 i (and f (face-attribute f :inherit)))
1616 (when (and (symbolp f) (or (not i) (not (listp i))))
1617 (insert (org-add-props (copy-sequence "1") nil 'face f))))
1618 (htmlize-region (point-min) (point-max))))
1619 (org-pop-to-buffer-same-window "*html*")
1620 (goto-char (point-min))
1621 (if (re-search-forward "<style" nil t)
1622 (delete-region (point-min) (match-beginning 0)))
1623 (if (re-search-forward "</style>" nil t)
1624 (delete-region (1+ (match-end 0)) (point-max)))
1625 (beginning-of-line 1)
1626 (if (looking-at " +") (replace-match ""))
1627 (goto-char (point-min)))
1629 (defun org-html--make-string (n string)
1630 "Build a string by concatenating N times STRING."
1631 (let (out) (dotimes (i n out) (setq out (concat string out)))))
1633 (defun org-html-fix-class-name (kwd) ; audit callers of this function
1634 "Turn todo keyword KWD into a valid class name.
1635 Replaces invalid characters with \"_\"."
1636 (save-match-data
1637 (while (string-match "[^a-zA-Z0-9_]" kwd)
1638 (setq kwd (replace-match "_" t t kwd))))
1639 kwd)
1641 (defun org-html-footnote-section (info)
1642 "Format the footnote section.
1643 INFO is a plist used as a communication channel."
1644 (let* ((fn-alist (org-export-collect-footnote-definitions info))
1645 (fn-alist
1646 (loop for (n type raw) in fn-alist collect
1647 (cons n (if (eq (org-element-type raw) 'org-data)
1648 (org-trim (org-export-data raw info))
1649 (format "<div class=\"footpara\">%s</div>"
1650 (org-trim (org-export-data raw info))))))))
1651 (when fn-alist
1652 (format
1653 (plist-get info :html-footnotes-section)
1654 (org-html--translate "Footnotes" info)
1655 (format
1656 "\n%s\n"
1657 (mapconcat
1658 (lambda (fn)
1659 (let ((n (car fn)) (def (cdr fn)))
1660 (format
1661 "<div class=\"footdef\">%s %s</div>\n"
1662 (format
1663 (plist-get info :html-footnote-format)
1664 (org-html--anchor
1665 (format "fn.%d" n)
1667 (format " class=\"footnum\" href=\"#fnr.%d\"" n)
1668 info))
1669 def)))
1670 fn-alist
1671 "\n"))))))
1674 ;;; Template
1676 (defun org-html--build-meta-info (info)
1677 "Return meta tags for exported document.
1678 INFO is a plist used as a communication channel."
1679 (let ((protect-string
1680 (lambda (str)
1681 (replace-regexp-in-string
1682 "\"" "&quot;" (org-html-encode-plain-text str))))
1683 (title (org-export-data (plist-get info :title) info))
1684 (author (and (plist-get info :with-author)
1685 (let ((auth (plist-get info :author)))
1686 (and auth
1687 ;; Return raw Org syntax, skipping non
1688 ;; exportable objects.
1689 (org-element-interpret-data
1690 (org-element-map auth
1691 (cons 'plain-text org-element-all-objects)
1692 'identity info))))))
1693 (description (plist-get info :description))
1694 (keywords (plist-get info :keywords))
1695 (charset (or (and org-html-coding-system
1696 (fboundp 'coding-system-get)
1697 (coding-system-get org-html-coding-system
1698 'mime-charset))
1699 "iso-8859-1")))
1700 (concat
1701 (when (plist-get info :time-stamp-file)
1702 (format-time-string
1703 (concat "<!-- "
1704 (plist-get info :html-metadata-timestamp-format)
1705 " -->\n")))
1706 (format
1707 (if (org-html-html5-p info)
1708 (org-html-close-tag "meta" " charset=\"%s\"" info)
1709 (org-html-close-tag
1710 "meta" " http-equiv=\"Content-Type\" content=\"text/html;charset=%s\""
1711 info))
1712 charset) "\n"
1713 (let ((viewport-options
1714 (org-remove-if-not (lambda (cell) (org-string-nw-p (cadr cell)))
1715 (plist-get info :html-viewport))))
1716 (and viewport-options
1717 (concat
1718 (org-html-close-tag
1719 "meta"
1720 (format " name=\"viewport\" content=\"%s\""
1721 (mapconcat
1722 (lambda (elm) (format "%s=%s" (car elm) (cadr elm)))
1723 viewport-options ", "))
1724 info)
1725 "\n")))
1726 (format "<title>%s</title>\n" title)
1727 (org-html-close-tag "meta" " name=\"generator\" content=\"Org-mode\"" info)
1728 "\n"
1729 (and (org-string-nw-p author)
1730 (concat
1731 (org-html-close-tag "meta"
1732 (format " name=\"author\" content=\"%s\""
1733 (funcall protect-string author))
1734 info)
1735 "\n"))
1736 (and (org-string-nw-p description)
1737 (concat
1738 (org-html-close-tag "meta"
1739 (format " name=\"description\" content=\"%s\"\n"
1740 (funcall protect-string description))
1741 info)
1742 "\n"))
1743 (and (org-string-nw-p keywords)
1744 (concat
1745 (org-html-close-tag "meta"
1746 (format " name=\"keywords\" content=\"%s\""
1747 (funcall protect-string keywords))
1748 info)
1749 "\n")))))
1751 (defun org-html--build-head (info)
1752 "Return information for the <head>..</head> of the HTML output.
1753 INFO is a plist used as a communication channel."
1754 (org-element-normalize-string
1755 (concat
1756 (when (plist-get info :html-head-include-default-style)
1757 (org-element-normalize-string org-html-style-default))
1758 (org-element-normalize-string (plist-get info :html-head))
1759 (org-element-normalize-string (plist-get info :html-head-extra))
1760 (when (and (plist-get info :html-htmlized-css-url)
1761 (eq org-html-htmlize-output-type 'css))
1762 (org-html-close-tag "link"
1763 (format " rel=\"stylesheet\" href=\"%s\" type=\"text/css\""
1764 (plist-get info :html-htmlized-css-url))
1765 info))
1766 (when (plist-get info :html-head-include-scripts) org-html-scripts))))
1768 (defun org-html--build-mathjax-config (info)
1769 "Insert the user setup into the mathjax template.
1770 INFO is a plist used as a communication channel."
1771 (when (and (memq (plist-get info :with-latex) '(mathjax t))
1772 (org-element-map (plist-get info :parse-tree)
1773 '(latex-fragment latex-environment) 'identity info t))
1774 (let ((template (plist-get info :html-mathjax-template))
1775 (options (plist-get info :html-mathjax-options))
1776 (in-buffer (or (plist-get info :html-mathjax) ""))
1777 name val x)
1778 (mapc
1779 (lambda (e)
1780 (setq name (car e) val (nth 1 e))
1781 (if (string-match (concat "\\<" (symbol-name name) ":") in-buffer)
1782 (setq val (car (read-from-string
1783 (substring in-buffer (match-end 0))))))
1784 (if (not (stringp val)) (setq val (format "%s" val)))
1785 (while (string-match (concat "%" (upcase (symbol-name name))) template)
1786 (setq template (replace-match val t t template))))
1787 options)
1788 ;; Return the modified template.
1789 (org-element-normalize-string template))))
1791 (defun org-html-format-spec (info)
1792 "Return format specification for elements that can be
1793 used in the preamble or postamble."
1794 `((?t . ,(org-export-data (plist-get info :title) info))
1795 (?s . ,(org-export-data (plist-get info :subtitle) info))
1796 (?d . ,(org-export-data (org-export-get-date info) info))
1797 (?T . ,(format-time-string
1798 (plist-get info :html-metadata-timestamp-format)))
1799 (?a . ,(org-export-data (plist-get info :author) info))
1800 (?e . ,(mapconcat
1801 (lambda (e)
1802 (format "<a href=\"mailto:%s\">%s</a>" e e))
1803 (split-string (plist-get info :email) ",+ *")
1804 ", "))
1805 (?c . ,(plist-get info :creator))
1806 (?C . ,(let ((file (plist-get info :input-file)))
1807 (format-time-string
1808 (plist-get info :html-metadata-timestamp-format)
1809 (when file (nth 5 (file-attributes file))))))
1810 (?v . ,(or (plist-get info :html-validation-link) ""))))
1812 (defun org-html--build-pre/postamble (type info)
1813 "Return document preamble or postamble as a string, or nil.
1814 TYPE is either `preamble' or `postamble', INFO is a plist used as a
1815 communication channel."
1816 (let ((section (plist-get info (intern (format ":html-%s" type))))
1817 (spec (org-html-format-spec info)))
1818 (when section
1819 (let ((section-contents
1820 (if (functionp section) (funcall section info)
1821 (cond
1822 ((stringp section) (format-spec section spec))
1823 ((eq section 'auto)
1824 (let ((date (cdr (assq ?d spec)))
1825 (author (cdr (assq ?a spec)))
1826 (email (cdr (assq ?e spec)))
1827 (creator (cdr (assq ?c spec)))
1828 (timestamp (cdr (assq ?T spec)))
1829 (validation-link (cdr (assq ?v spec))))
1830 (concat
1831 (when (and (plist-get info :with-date)
1832 (org-string-nw-p date))
1833 (format "<p class=\"date\">%s: %s</p>\n"
1834 (org-html--translate "Date" info)
1835 date))
1836 (when (and (plist-get info :with-author)
1837 (org-string-nw-p author))
1838 (format "<p class=\"author\">%s: %s</p>\n"
1839 (org-html--translate "Author" info)
1840 author))
1841 (when (and (plist-get info :with-email)
1842 (org-string-nw-p email))
1843 (format "<p class=\"email\">%s: %s</p>\n"
1844 (org-html--translate "Email" info)
1845 email))
1846 (when (plist-get info :time-stamp-file)
1847 (format
1848 "<p class=\"date\">%s: %s</p>\n"
1849 (org-html--translate "Created" info)
1850 (format-time-string
1851 (plist-get info :html-metadata-timestamp-format))))
1852 (when (plist-get info :with-creator)
1853 (format "<p class=\"creator\">%s</p>\n" creator))
1854 (format "<p class=\"validation\">%s</p>\n"
1855 validation-link))))
1856 (t (format-spec
1857 (or (cadr (assoc
1858 (plist-get info :language)
1859 (eval (intern
1860 (format "org-html-%s-format" type)))))
1861 (cadr
1862 (assoc
1863 "en"
1864 (eval
1865 (intern (format "org-html-%s-format" type))))))
1866 spec))))))
1867 (let ((div (assq type (plist-get info :html-divs))))
1868 (when (org-string-nw-p section-contents)
1869 (concat
1870 (format "<%s id=\"%s\" class=\"%s\">\n"
1871 (nth 1 div)
1872 (nth 2 div)
1873 org-html--pre/postamble-class)
1874 (org-element-normalize-string section-contents)
1875 (format "</%s>\n" (nth 1 div)))))))))
1877 (defun org-html-inner-template (contents info)
1878 "Return body of document string after HTML conversion.
1879 CONTENTS is the transcoded contents string. INFO is a plist
1880 holding export options."
1881 (concat
1882 ;; Table of contents.
1883 (let ((depth (plist-get info :with-toc)))
1884 (when depth (org-html-toc depth info)))
1885 ;; Document contents.
1886 contents
1887 ;; Footnotes section.
1888 (org-html-footnote-section info)))
1890 (defun org-html-template (contents info)
1891 "Return complete document string after HTML conversion.
1892 CONTENTS is the transcoded contents string. INFO is a plist
1893 holding export options."
1894 (concat
1895 (when (and (not (org-html-html5-p info)) (org-html-xhtml-p info))
1896 (let* ((xml-declaration (plist-get info :html-xml-declaration))
1897 (decl (or (and (stringp xml-declaration) xml-declaration)
1898 (cdr (assoc (plist-get info :html-extension)
1899 xml-declaration))
1900 (cdr (assoc "html" xml-declaration))
1901 "")))
1902 (when (not (or (not decl) (string= "" decl)))
1903 (format "%s\n"
1904 (format decl
1905 (or (and org-html-coding-system
1906 (fboundp 'coding-system-get)
1907 (coding-system-get org-html-coding-system 'mime-charset))
1908 "iso-8859-1"))))))
1909 (org-html-doctype info)
1910 "\n"
1911 (concat "<html"
1912 (when (org-html-xhtml-p info)
1913 (format
1914 " xmlns=\"http://www.w3.org/1999/xhtml\" lang=\"%s\" xml:lang=\"%s\""
1915 (plist-get info :language) (plist-get info :language)))
1916 ">\n")
1917 "<head>\n"
1918 (org-html--build-meta-info info)
1919 (org-html--build-head info)
1920 (org-html--build-mathjax-config info)
1921 "</head>\n"
1922 "<body>\n"
1923 (let ((link-up (org-trim (plist-get info :html-link-up)))
1924 (link-home (org-trim (plist-get info :html-link-home))))
1925 (unless (and (string= link-up "") (string= link-home ""))
1926 (format (plist-get info :html-home/up-format)
1927 (or link-up link-home)
1928 (or link-home link-up))))
1929 ;; Preamble.
1930 (org-html--build-pre/postamble 'preamble info)
1931 ;; Document contents.
1932 (let ((div (assq 'content (plist-get info :html-divs))))
1933 (format "<%s id=\"%s\">\n" (nth 1 div) (nth 2 div)))
1934 ;; Document title.
1935 (when (plist-get info :with-title)
1936 (let ((title (plist-get info :title))
1937 (subtitle (plist-get info :subtitle))
1938 (html5-fancy (org-html--html5-fancy-p info)))
1939 (when title
1940 (format
1941 (if html5-fancy
1942 "<header>\n<h1 class=\"title\">%s</h1>\n%s</header>"
1943 "<h1 class=\"title\">%s%s</h1>\n")
1944 (org-export-data title info)
1945 (if subtitle
1946 (format
1947 (if html5-fancy
1948 "<p class=\"subtitle\">%s</p>\n"
1949 "\n<br>\n<span class=\"subtitle\">%s</span>\n")
1950 (org-export-data subtitle info))
1951 "")))))
1952 contents
1953 (format "</%s>\n" (nth 1 (assq 'content (plist-get info :html-divs))))
1954 ;; Postamble.
1955 (org-html--build-pre/postamble 'postamble info)
1956 ;; Closing document.
1957 "</body>\n</html>"))
1959 (defun org-html--translate (s info)
1960 "Translate string S according to specified language.
1961 INFO is a plist used as a communication channel."
1962 (org-export-translate s :html info))
1964 ;;;; Anchor
1966 (defun org-html--anchor (id desc attributes info)
1967 "Format a HTML anchor."
1968 (let* ((name (and (plist-get info :html-allow-name-attribute-in-anchors) id))
1969 (attributes (concat (and id (format " id=\"%s\"" id))
1970 (and name (format " name=\"%s\"" name))
1971 attributes)))
1972 (format "<a%s>%s</a>" attributes (or desc ""))))
1974 ;;;; Todo
1976 (defun org-html--todo (todo info)
1977 "Format TODO keywords into HTML."
1978 (when todo
1979 (format "<span class=\"%s %s%s\">%s</span>"
1980 (if (member todo org-done-keywords) "done" "todo")
1981 (plist-get info :html-todo-kwd-class-prefix)
1982 (org-html-fix-class-name todo)
1983 todo)))
1985 ;;;; Priority
1987 (defun org-html--priority (priority info)
1988 "Format a priority into HTML.
1989 PRIORITY is the character code of the priority or nil. INFO is
1990 a plist containing export options."
1991 (and priority (format "<span class=\"priority\">[%c]</span>" priority)))
1993 ;;;; Tags
1995 (defun org-html--tags (tags info)
1996 "Format TAGS into HTML.
1997 INFO is a plist containing export options."
1998 (when tags
1999 (format "<span class=\"tag\">%s</span>"
2000 (mapconcat
2001 (lambda (tag)
2002 (format "<span class=\"%s\">%s</span>"
2003 (concat (plist-get info :html-tag-class-prefix)
2004 (org-html-fix-class-name tag))
2005 tag))
2006 tags "&#xa0;"))))
2008 ;;;; Src Code
2010 (defun org-html-fontify-code (code lang)
2011 "Color CODE with htmlize library.
2012 CODE is a string representing the source code to colorize. LANG
2013 is the language used for CODE, as a string, or nil."
2014 (when code
2015 (cond
2016 ;; Case 1: No lang. Possibly an example block.
2017 ((not lang)
2018 ;; Simple transcoding.
2019 (org-html-encode-plain-text code))
2020 ;; Case 2: No htmlize or an inferior version of htmlize
2021 ((not (and (require 'htmlize nil t) (fboundp 'htmlize-region-for-paste)))
2022 ;; Emit a warning.
2023 (message "Cannot fontify src block (htmlize.el >= 1.34 required)")
2024 ;; Simple transcoding.
2025 (org-html-encode-plain-text code))
2026 ;; Case 3: plain text explicitly set
2027 ((not org-html-htmlize-output-type)
2028 ;; Simple transcoding.
2029 (org-html-encode-plain-text code))
2031 ;; Map language
2032 (setq lang (or (assoc-default lang org-src-lang-modes) lang))
2033 (let* ((lang-mode (and lang (intern (format "%s-mode" lang)))))
2034 (cond
2035 ;; Case 1: Language is not associated with any Emacs mode
2036 ((not (functionp lang-mode))
2037 ;; Simple transcoding.
2038 (org-html-encode-plain-text code))
2039 ;; Case 2: Default. Fontify code.
2041 ;; htmlize
2042 (setq code
2043 (let ((output-type org-html-htmlize-output-type)
2044 (font-prefix org-html-htmlize-font-prefix))
2045 (with-temp-buffer
2046 ;; Switch to language-specific mode.
2047 (funcall lang-mode)
2048 (insert code)
2049 ;; Fontify buffer.
2050 (org-font-lock-ensure)
2051 ;; Remove formatting on newline characters.
2052 (save-excursion
2053 (let ((beg (point-min))
2054 (end (point-max)))
2055 (goto-char beg)
2056 (while (progn (end-of-line) (< (point) end))
2057 (put-text-property (point) (1+ (point)) 'face nil)
2058 (forward-char 1))))
2059 (org-src-mode)
2060 (set-buffer-modified-p nil)
2061 ;; Htmlize region.
2062 (let ((org-html-htmlize-output-type output-type)
2063 (org-html-htmlize-font-prefix font-prefix))
2064 (org-html-htmlize-region-for-paste
2065 (point-min) (point-max))))))
2066 ;; Strip any enclosing <pre></pre> tags.
2067 (let* ((beg (and (string-match "\\`<pre[^>]*>\n*" code) (match-end 0)))
2068 (end (and beg (string-match "</pre>\\'" code))))
2069 (if (and beg end) (substring code beg end) code)))))))))
2071 (defun org-html-do-format-code
2072 (code &optional lang refs retain-labels num-start)
2073 "Format CODE string as source code.
2074 Optional arguments LANG, REFS, RETAIN-LABELS and NUM-START are,
2075 respectively, the language of the source code, as a string, an
2076 alist between line numbers and references (as returned by
2077 `org-export-unravel-code'), a boolean specifying if labels should
2078 appear in the source code, and the number associated to the first
2079 line of code."
2080 (let* ((code-lines (org-split-string code "\n"))
2081 (code-length (length code-lines))
2082 (num-fmt
2083 (and num-start
2084 (format "%%%ds: "
2085 (length (number-to-string (+ code-length num-start))))))
2086 (code (org-html-fontify-code code lang)))
2087 (org-export-format-code
2088 code
2089 (lambda (loc line-num ref)
2090 (setq loc
2091 (concat
2092 ;; Add line number, if needed.
2093 (when num-start
2094 (format "<span class=\"linenr\">%s</span>"
2095 (format num-fmt line-num)))
2096 ;; Transcoded src line.
2098 ;; Add label, if needed.
2099 (when (and ref retain-labels) (format " (%s)" ref))))
2100 ;; Mark transcoded line as an anchor, if needed.
2101 (if (not ref) loc
2102 (format "<span id=\"coderef-%s\" class=\"coderef-off\">%s</span>"
2103 ref loc)))
2104 num-start refs)))
2106 (defun org-html-format-code (element info)
2107 "Format contents of ELEMENT as source code.
2108 ELEMENT is either an example block or a src block. INFO is
2109 a plist used as a communication channel."
2110 (let* ((lang (org-element-property :language element))
2111 ;; Extract code and references.
2112 (code-info (org-export-unravel-code element))
2113 (code (car code-info))
2114 (refs (cdr code-info))
2115 ;; Does the src block contain labels?
2116 (retain-labels (org-element-property :retain-labels element))
2117 ;; Does it have line numbers?
2118 (num-start (case (org-element-property :number-lines element)
2119 (continued (org-export-get-loc element info))
2120 (new 0))))
2121 (org-html-do-format-code code lang refs retain-labels num-start)))
2124 ;;; Tables of Contents
2126 (defun org-html-toc (depth info &optional scope)
2127 "Build a table of contents.
2128 DEPTH is an integer specifying the depth of the table. INFO is
2129 a plist used as a communication channel. Optional argument SCOPE
2130 is an element defining the scope of the table. Return the table
2131 of contents as a string, or nil if it is empty."
2132 (let ((toc-entries
2133 (mapcar (lambda (headline)
2134 (cons (org-html--format-toc-headline headline info)
2135 (org-export-get-relative-level headline info)))
2136 (org-export-collect-headlines info depth scope))))
2137 (when toc-entries
2138 (let ((toc (concat "<div id=\"text-table-of-contents\">"
2139 (org-html--toc-text toc-entries)
2140 "</div>\n")))
2141 (if scope toc
2142 (let ((outer-tag (if (org-html--html5-fancy-p info)
2143 "nav"
2144 "div")))
2145 (concat (format "<%s id=\"table-of-contents\">\n" outer-tag)
2146 (let ((top-level (plist-get info :html-toplevel-hlevel)))
2147 (format "<h%d>%s</h%d>\n"
2148 top-level
2149 (org-html--translate "Table of Contents" info)
2150 top-level))
2152 (format "</%s>\n" outer-tag))))))))
2154 (defun org-html--toc-text (toc-entries)
2155 "Return innards of a table of contents, as a string.
2156 TOC-ENTRIES is an alist where key is an entry title, as a string,
2157 and value is its relative level, as an integer."
2158 (let* ((prev-level (1- (cdar toc-entries)))
2159 (start-level prev-level))
2160 (concat
2161 (mapconcat
2162 (lambda (entry)
2163 (let ((headline (car entry))
2164 (level (cdr entry)))
2165 (concat
2166 (let* ((cnt (- level prev-level))
2167 (times (if (> cnt 0) (1- cnt) (- cnt)))
2168 rtn)
2169 (setq prev-level level)
2170 (concat
2171 (org-html--make-string
2172 times (cond ((> cnt 0) "\n<ul>\n<li>")
2173 ((< cnt 0) "</li>\n</ul>\n")))
2174 (if (> cnt 0) "\n<ul>\n<li>" "</li>\n<li>")))
2175 headline)))
2176 toc-entries "")
2177 (org-html--make-string (- prev-level start-level) "</li>\n</ul>\n"))))
2179 (defun org-html--format-toc-headline (headline info)
2180 "Return an appropriate table of contents entry for HEADLINE.
2181 INFO is a plist used as a communication channel."
2182 (let* ((headline-number (org-export-get-headline-number headline info))
2183 (todo (and (plist-get info :with-todo-keywords)
2184 (let ((todo (org-element-property :todo-keyword headline)))
2185 (and todo (org-export-data todo info)))))
2186 (todo-type (and todo (org-element-property :todo-type headline)))
2187 (priority (and (plist-get info :with-priority)
2188 (org-element-property :priority headline)))
2189 (text (org-export-data-with-backend
2190 (org-export-get-alt-title headline info)
2191 ;; Create an anonymous back-end that will ignore any
2192 ;; footnote-reference, link, radio-target and target
2193 ;; in table of contents.
2194 (org-export-create-backend
2195 :parent 'html
2196 :transcoders '((footnote-reference . ignore)
2197 (link . (lambda (object c i) c))
2198 (radio-target . (lambda (object c i) c))
2199 (target . ignore)))
2200 info))
2201 (tags (and (eq (plist-get info :with-tags) t)
2202 (org-export-get-tags headline info))))
2203 (format "<a href=\"#%s\">%s</a>"
2204 ;; Label.
2205 (or (org-element-property :CUSTOM_ID headline)
2206 (org-export-get-reference headline info))
2207 ;; Body.
2208 (concat
2209 (and (not (org-export-low-level-p headline info))
2210 (org-export-numbered-headline-p headline info)
2211 (concat (mapconcat #'number-to-string headline-number ".")
2212 ". "))
2213 (apply (plist-get info :html-format-headline-function)
2214 todo todo-type priority text tags :section-number nil)))))
2216 (defun org-html-list-of-listings (info)
2217 "Build a list of listings.
2218 INFO is a plist used as a communication channel. Return the list
2219 of listings as a string, or nil if it is empty."
2220 (let ((lol-entries (org-export-collect-listings info)))
2221 (when lol-entries
2222 (concat "<div id=\"list-of-listings\">\n"
2223 (let ((top-level (plist-get info :html-toplevel-hlevel)))
2224 (format "<h%d>%s</h%d>\n"
2225 top-level
2226 (org-html--translate "List of Listings" info)
2227 top-level))
2228 "<div id=\"text-list-of-listings\">\n<ul>\n"
2229 (let ((count 0)
2230 (initial-fmt (format "<span class=\"listing-number\">%s</span>"
2231 (org-html--translate "Listing %d:" info))))
2232 (mapconcat
2233 (lambda (entry)
2234 (let ((label (and (org-element-property :name entry)
2235 (org-export-get-reference entry info)))
2236 (title (org-trim
2237 (org-export-data
2238 (or (org-export-get-caption entry t)
2239 (org-export-get-caption entry))
2240 info))))
2241 (concat
2242 "<li>"
2243 (if (not label)
2244 (concat (format initial-fmt (incf count)) " " title)
2245 (format "<a href=\"#%s\">%s %s</a>"
2246 label
2247 (format initial-fmt (incf count))
2248 title))
2249 "</li>")))
2250 lol-entries "\n"))
2251 "\n</ul>\n</div>\n</div>"))))
2253 (defun org-html-list-of-tables (info)
2254 "Build a list of tables.
2255 INFO is a plist used as a communication channel. Return the list
2256 of tables as a string, or nil if it is empty."
2257 (let ((lol-entries (org-export-collect-tables info)))
2258 (when lol-entries
2259 (concat "<div id=\"list-of-tables\">\n"
2260 (let ((top-level (plist-get info :html-toplevel-hlevel)))
2261 (format "<h%d>%s</h%d>\n"
2262 top-level
2263 (org-html--translate "List of Tables" info)
2264 top-level))
2265 "<div id=\"text-list-of-tables\">\n<ul>\n"
2266 (let ((count 0)
2267 (initial-fmt (format "<span class=\"table-number\">%s</span>"
2268 (org-html--translate "Table %d:" info))))
2269 (mapconcat
2270 (lambda (entry)
2271 (let ((label (and (org-element-property :name entry)
2272 (org-export-get-reference entry info)))
2273 (title (org-trim
2274 (org-export-data
2275 (or (org-export-get-caption entry t)
2276 (org-export-get-caption entry))
2277 info))))
2278 (concat
2279 "<li>"
2280 (if (not label)
2281 (concat (format initial-fmt (incf count)) " " title)
2282 (format "<a href=\"#%s\">%s %s</a>"
2283 label
2284 (format initial-fmt (incf count))
2285 title))
2286 "</li>")))
2287 lol-entries "\n"))
2288 "\n</ul>\n</div>\n</div>"))))
2291 ;;; Transcode Functions
2293 ;;;; Bold
2295 (defun org-html-bold (bold contents info)
2296 "Transcode BOLD from Org to HTML.
2297 CONTENTS is the text with bold markup. INFO is a plist holding
2298 contextual information."
2299 (format (or (cdr (assq 'bold (plist-get info :html-text-markup-alist))) "%s")
2300 contents))
2302 ;;;; Center Block
2304 (defun org-html-center-block (center-block contents info)
2305 "Transcode a CENTER-BLOCK element from Org to HTML.
2306 CONTENTS holds the contents of the block. INFO is a plist
2307 holding contextual information."
2308 (format "<div class=\"org-center\">\n%s</div>" contents))
2310 ;;;; Clock
2312 (defun org-html-clock (clock contents info)
2313 "Transcode a CLOCK element from Org to HTML.
2314 CONTENTS is nil. INFO is a plist used as a communication
2315 channel."
2316 (format "<p>
2317 <span class=\"timestamp-wrapper\">
2318 <span class=\"timestamp-kwd\">%s</span> <span class=\"timestamp\">%s</span>%s
2319 </span>
2320 </p>"
2321 org-clock-string
2322 (org-timestamp-translate (org-element-property :value clock))
2323 (let ((time (org-element-property :duration clock)))
2324 (and time (format " <span class=\"timestamp\">(%s)</span>" time)))))
2326 ;;;; Code
2328 (defun org-html-code (code contents info)
2329 "Transcode CODE from Org to HTML.
2330 CONTENTS is nil. INFO is a plist holding contextual
2331 information."
2332 (format (or (cdr (assq 'code (plist-get info :html-text-markup-alist))) "%s")
2333 (org-html-encode-plain-text (org-element-property :value code))))
2335 ;;;; Drawer
2337 (defun org-html-drawer (drawer contents info)
2338 "Transcode a DRAWER element from Org to HTML.
2339 CONTENTS holds the contents of the block. INFO is a plist
2340 holding contextual information."
2341 (funcall (plist-get info :html-format-drawer-function)
2342 (org-element-property :drawer-name drawer)
2343 contents))
2345 ;;;; Dynamic Block
2347 (defun org-html-dynamic-block (dynamic-block contents info)
2348 "Transcode a DYNAMIC-BLOCK element from Org to HTML.
2349 CONTENTS holds the contents of the block. INFO is a plist
2350 holding contextual information. See `org-export-data'."
2351 contents)
2353 ;;;; Entity
2355 (defun org-html-entity (entity contents info)
2356 "Transcode an ENTITY object from Org to HTML.
2357 CONTENTS are the definition itself. INFO is a plist holding
2358 contextual information."
2359 (org-element-property :html entity))
2361 ;;;; Example Block
2363 (defun org-html-example-block (example-block contents info)
2364 "Transcode a EXAMPLE-BLOCK element from Org to HTML.
2365 CONTENTS is nil. INFO is a plist holding contextual
2366 information."
2367 (if (org-export-read-attribute :attr_html example-block :textarea)
2368 (org-html--textarea-block example-block)
2369 (format "<pre class=\"example\">\n%s</pre>"
2370 (org-html-format-code example-block info))))
2372 ;;;; Export Snippet
2374 (defun org-html-export-snippet (export-snippet contents info)
2375 "Transcode a EXPORT-SNIPPET object from Org to HTML.
2376 CONTENTS is nil. INFO is a plist holding contextual
2377 information."
2378 (when (eq (org-export-snippet-backend export-snippet) 'html)
2379 (org-element-property :value export-snippet)))
2381 ;;;; Export Block
2383 (defun org-html-export-block (export-block contents info)
2384 "Transcode a EXPORT-BLOCK element from Org to HTML.
2385 CONTENTS is nil. INFO is a plist holding contextual information."
2386 (when (string= (org-element-property :type export-block) "HTML")
2387 (org-remove-indentation (org-element-property :value export-block))))
2389 ;;;; Fixed Width
2391 (defun org-html-fixed-width (fixed-width contents info)
2392 "Transcode a FIXED-WIDTH element from Org to HTML.
2393 CONTENTS is nil. INFO is a plist holding contextual information."
2394 (format "<pre class=\"example\">\n%s</pre>"
2395 (org-html-do-format-code
2396 (org-remove-indentation
2397 (org-element-property :value fixed-width)))))
2399 ;;;; Footnote Reference
2401 (defun org-html-footnote-reference (footnote-reference contents info)
2402 "Transcode a FOOTNOTE-REFERENCE element from Org to HTML.
2403 CONTENTS is nil. INFO is a plist holding contextual information."
2404 (concat
2405 ;; Insert separator between two footnotes in a row.
2406 (let ((prev (org-export-get-previous-element footnote-reference info)))
2407 (when (eq (org-element-type prev) 'footnote-reference)
2408 (plist-get info :html-footnote-separator)))
2409 (let* ((n (org-export-get-footnote-number footnote-reference info))
2410 (id (format "fnr.%d%s"
2412 (if (org-export-footnote-first-reference-p
2413 footnote-reference info)
2415 ".100"))))
2416 (format
2417 (plist-get info :html-footnote-format)
2418 (org-html--anchor
2419 id n (format " class=\"footref\" href=\"#fn.%d\"" n) info)))))
2421 ;;;; Headline
2423 (defun org-html-headline (headline contents info)
2424 "Transcode a HEADLINE element from Org to HTML.
2425 CONTENTS holds the contents of the headline. INFO is a plist
2426 holding contextual information."
2427 (unless (org-element-property :footnote-section-p headline)
2428 (let* ((numberedp (org-export-numbered-headline-p headline info))
2429 (numbers (org-export-get-headline-number headline info))
2430 (section-number (and numbers
2431 (mapconcat #'number-to-string numbers "-")))
2432 (level (+ (org-export-get-relative-level headline info)
2433 (1- (plist-get info :html-toplevel-hlevel))))
2434 (todo (and (plist-get info :with-todo-keywords)
2435 (let ((todo (org-element-property :todo-keyword headline)))
2436 (and todo (org-export-data todo info)))))
2437 (todo-type (and todo (org-element-property :todo-type headline)))
2438 (priority (and (plist-get info :with-priority)
2439 (org-element-property :priority headline)))
2440 (text (org-export-data (org-element-property :title headline) info))
2441 (tags (and (plist-get info :with-tags)
2442 (org-export-get-tags headline info)))
2443 (full-text (funcall (plist-get info :html-format-headline-function)
2444 todo todo-type priority text tags info))
2445 (contents (or contents ""))
2446 (ids (delq nil
2447 (list (org-element-property :CUSTOM_ID headline)
2448 (org-export-get-reference headline info)
2449 (org-element-property :ID headline))))
2450 (preferred-id (car ids))
2451 (extra-ids
2452 (mapconcat
2453 (lambda (id)
2454 (org-html--anchor
2455 (if (org-uuidgen-p id) (concat "ID-" id) id)
2456 nil nil info))
2457 (cdr ids) "")))
2458 (if (org-export-low-level-p headline info)
2459 ;; This is a deep sub-tree: export it as a list item.
2460 (let* ((type (if numberedp 'ordered 'unordered))
2461 (itemized-body
2462 (org-html-format-list-item
2463 contents type nil info nil
2464 (concat (org-html--anchor preferred-id nil nil info)
2465 extra-ids
2466 full-text))))
2467 (concat (and (org-export-first-sibling-p headline info)
2468 (org-html-begin-plain-list type))
2469 itemized-body
2470 (and (org-export-last-sibling-p headline info)
2471 (org-html-end-plain-list type))))
2472 (let ((extra-class (org-element-property :HTML_CONTAINER_CLASS headline))
2473 (first-content (car (org-element-contents headline))))
2474 ;; Standard headline. Export it as a section.
2475 (format "<%s id=\"%s\" class=\"%s\">%s%s</%s>\n"
2476 (org-html--container headline info)
2477 (concat "outline-container-"
2478 (org-export-get-reference headline info))
2479 (concat (format "outline-%d" level)
2480 (and extra-class " ")
2481 extra-class)
2482 (format "\n<h%d id=\"%s\">%s%s</h%d>\n"
2483 level
2484 preferred-id
2485 extra-ids
2486 (concat
2487 (and numberedp
2488 (format
2489 "<span class=\"section-number-%d\">%s</span> "
2490 level
2491 (mapconcat #'number-to-string numbers ".")))
2492 full-text)
2493 level)
2494 ;; When there is no section, pretend there is an
2495 ;; empty one to get the correct <div
2496 ;; class="outline-...> which is needed by
2497 ;; `org-info.js'.
2498 (if (eq (org-element-type first-content) 'section) contents
2499 (concat (org-html-section first-content "" info) contents))
2500 (org-html--container headline info)))))))
2502 (defun org-html-format-headline-default-function
2503 (todo todo-type priority text tags info)
2504 "Default format function for a headline.
2505 See `org-html-format-headline-function' for details."
2506 (let ((todo (org-html--todo todo info))
2507 (priority (org-html--priority priority info))
2508 (tags (org-html--tags tags info)))
2509 (concat todo (and todo " ")
2510 priority (and priority " ")
2511 text
2512 (and tags "&#xa0;&#xa0;&#xa0;") tags)))
2514 (defun org-html--container (headline info)
2515 (or (org-element-property :HTML_CONTAINER headline)
2516 (if (= 1 (org-export-get-relative-level headline info))
2517 (plist-get info :html-container)
2518 "div")))
2520 ;;;; Horizontal Rule
2522 (defun org-html-horizontal-rule (horizontal-rule contents info)
2523 "Transcode an HORIZONTAL-RULE object from Org to HTML.
2524 CONTENTS is nil. INFO is a plist holding contextual information."
2525 (org-html-close-tag "hr" nil info))
2527 ;;;; Inline Src Block
2529 (defun org-html-inline-src-block (inline-src-block contents info)
2530 "Transcode an INLINE-SRC-BLOCK element from Org to HTML.
2531 CONTENTS holds the contents of the item. INFO is a plist holding
2532 contextual information."
2533 (let ((lang (org-element-property :language inline-src-block))
2534 (code (org-html-format-code inline-src-block info))
2535 (label
2536 (let ((lbl (and (org-element-property :name inline-src-block)
2537 (org-export-get-reference inline-src-block info))))
2538 (if (not lbl) "" (format " id=\"%s\"" lbl)))))
2539 (format "<code class=\"src src-%s\"%s>%s</code>" lang label code)))
2541 ;;;; Inlinetask
2543 (defun org-html-inlinetask (inlinetask contents info)
2544 "Transcode an INLINETASK element from Org to HTML.
2545 CONTENTS holds the contents of the block. INFO is a plist
2546 holding contextual information."
2547 (let* ((todo (and (plist-get info :with-todo-keywords)
2548 (let ((todo (org-element-property :todo-keyword inlinetask)))
2549 (and todo (org-export-data todo info)))))
2550 (todo-type (and todo (org-element-property :todo-type inlinetask)))
2551 (priority (and (plist-get info :with-priority)
2552 (org-element-property :priority inlinetask)))
2553 (text (org-export-data (org-element-property :title inlinetask) info))
2554 (tags (and (plist-get info :with-tags)
2555 (org-export-get-tags inlinetask info))))
2556 (funcall (plist-get info :html-format-inlinetask-function)
2557 todo todo-type priority text tags contents info)))
2559 (defun org-html-format-inlinetask-default-function
2560 (todo todo-type priority text tags contents info)
2561 "Default format function for a inlinetasks.
2562 See `org-html-format-inlinetask-function' for details."
2563 (format "<div class=\"inlinetask\">\n<b>%s</b>%s\n%s</div>"
2564 (org-html-format-headline-default-function
2565 todo todo-type priority text tags info)
2566 (org-html-close-tag "br" nil info)
2567 contents))
2569 ;;;; Italic
2571 (defun org-html-italic (italic contents info)
2572 "Transcode ITALIC from Org to HTML.
2573 CONTENTS is the text with italic markup. INFO is a plist holding
2574 contextual information."
2575 (format
2576 (or (cdr (assq 'italic (plist-get info :html-text-markup-alist))) "%s")
2577 contents))
2579 ;;;; Item
2581 (defun org-html-checkbox (checkbox info)
2582 "Format CHECKBOX into HTML.
2583 INFO is a plist holding contextual information. See
2584 `org-html-checkbox-type' for customization options."
2585 (cdr (assq checkbox
2586 (cdr (assq (plist-get info :html-checkbox-type)
2587 org-html-checkbox-types)))))
2589 (defun org-html-format-list-item (contents type checkbox info
2590 &optional term-counter-id
2591 headline)
2592 "Format a list item into HTML."
2593 (let ((class (if checkbox
2594 (format " class=\"%s\""
2595 (symbol-name checkbox)) ""))
2596 (checkbox (concat (org-html-checkbox checkbox info)
2597 (and checkbox " ")))
2598 (br (org-html-close-tag "br" nil info)))
2599 (concat
2600 (case type
2601 (ordered
2602 (let* ((counter term-counter-id)
2603 (extra (if counter (format " value=\"%s\"" counter) "")))
2604 (concat
2605 (format "<li%s%s>" class extra)
2606 (when headline (concat headline br)))))
2607 (unordered
2608 (let* ((id term-counter-id)
2609 (extra (if id (format " id=\"%s\"" id) "")))
2610 (concat
2611 (format "<li%s%s>" class extra)
2612 (when headline (concat headline br)))))
2613 (descriptive
2614 (let* ((term term-counter-id))
2615 (setq term (or term "(no term)"))
2616 ;; Check-boxes in descriptive lists are associated to tag.
2617 (concat (format "<dt%s>%s</dt>"
2618 class (concat checkbox term))
2619 "<dd>"))))
2620 (unless (eq type 'descriptive) checkbox)
2621 (and contents (org-trim contents))
2622 (case type
2623 (ordered "</li>")
2624 (unordered "</li>")
2625 (descriptive "</dd>")))))
2627 (defun org-html-item (item contents info)
2628 "Transcode an ITEM element from Org to HTML.
2629 CONTENTS holds the contents of the item. INFO is a plist holding
2630 contextual information."
2631 (let* ((plain-list (org-export-get-parent item))
2632 (type (org-element-property :type plain-list))
2633 (counter (org-element-property :counter item))
2634 (checkbox (org-element-property :checkbox item))
2635 (tag (let ((tag (org-element-property :tag item)))
2636 (and tag (org-export-data tag info)))))
2637 (org-html-format-list-item
2638 contents type checkbox info (or tag counter))))
2640 ;;;; Keyword
2642 (defun org-html-keyword (keyword contents info)
2643 "Transcode a KEYWORD element from Org to HTML.
2644 CONTENTS is nil. INFO is a plist holding contextual information."
2645 (let ((key (org-element-property :key keyword))
2646 (value (org-element-property :value keyword)))
2647 (cond
2648 ((string= key "HTML") value)
2649 ((string= key "TOC")
2650 (let ((case-fold-search t))
2651 (cond
2652 ((string-match "\\<headlines\\>" value)
2653 (let ((depth (and (string-match "\\<[0-9]+\\>" value)
2654 (string-to-number (match-string 0 value))))
2655 (localp (org-string-match-p "\\<local\\>" value)))
2656 (org-html-toc depth info (and localp keyword))))
2657 ((string= "listings" value) (org-html-list-of-listings info))
2658 ((string= "tables" value) (org-html-list-of-tables info))))))))
2660 ;;;; Latex Environment
2662 (defun org-html-format-latex (latex-frag processing-type info)
2663 "Format a LaTeX fragment LATEX-FRAG into HTML.
2664 PROCESSING-TYPE designates the tool used for conversion. It is
2665 a symbol among `mathjax', `dvipng', `imagemagick', `verbatim' nil
2666 and t. See `org-html-with-latex' for more information. INFO is
2667 a plist containing export properties."
2668 (let ((cache-relpath "") (cache-dir ""))
2669 (unless (eq processing-type 'mathjax)
2670 (let ((bfn (or (buffer-file-name)
2671 (make-temp-name
2672 (expand-file-name "latex" temporary-file-directory))))
2673 (latex-header
2674 (let ((header (plist-get info :latex-header)))
2675 (and header
2676 (concat (mapconcat
2677 (lambda (line) (concat "#+LATEX_HEADER: " line))
2678 (org-split-string header "\n")
2679 "\n")
2680 "\n")))))
2681 (setq cache-relpath
2682 (concat "ltxpng/"
2683 (file-name-sans-extension
2684 (file-name-nondirectory bfn)))
2685 cache-dir (file-name-directory bfn))
2686 ;; Re-create LaTeX environment from original buffer in
2687 ;; temporary buffer so that dvipng/imagemagick can properly
2688 ;; turn the fragment into an image.
2689 (setq latex-frag (concat latex-header latex-frag))))
2690 (with-temp-buffer
2691 (insert latex-frag)
2692 (org-format-latex cache-relpath cache-dir nil "Creating LaTeX Image..."
2693 nil processing-type)
2694 (buffer-string))))
2696 (defun org-html-latex-environment (latex-environment contents info)
2697 "Transcode a LATEX-ENVIRONMENT element from Org to HTML.
2698 CONTENTS is nil. INFO is a plist holding contextual information."
2699 (let ((processing-type (plist-get info :with-latex))
2700 (latex-frag (org-remove-indentation
2701 (org-element-property :value latex-environment)))
2702 (attributes (org-export-read-attribute :attr_html latex-environment)))
2703 (case processing-type
2704 ((t mathjax)
2705 (org-html-format-latex latex-frag 'mathjax info))
2706 ((dvipng imagemagick)
2707 (let ((formula-link
2708 (org-html-format-latex latex-frag processing-type info)))
2709 (when (and formula-link (string-match "file:\\([^]]*\\)" formula-link))
2710 ;; Do not provide a caption or a name to be consistent with
2711 ;; `mathjax' handling.
2712 (org-html--wrap-image
2713 (org-html--format-image
2714 (match-string 1 formula-link) attributes info) info))))
2715 (t latex-frag))))
2717 ;;;; Latex Fragment
2719 (defun org-html-latex-fragment (latex-fragment contents info)
2720 "Transcode a LATEX-FRAGMENT object from Org to HTML.
2721 CONTENTS is nil. INFO is a plist holding contextual information."
2722 (let ((latex-frag (org-element-property :value latex-fragment))
2723 (processing-type (plist-get info :with-latex)))
2724 (case processing-type
2725 ((t mathjax)
2726 (org-html-format-latex latex-frag 'mathjax info))
2727 ((dvipng imagemagick)
2728 (let ((formula-link
2729 (org-html-format-latex latex-frag processing-type info)))
2730 (when (and formula-link (string-match "file:\\([^]]*\\)" formula-link))
2731 (org-html--format-image (match-string 1 formula-link) nil info))))
2732 (t latex-frag))))
2734 ;;;; Line Break
2736 (defun org-html-line-break (line-break contents info)
2737 "Transcode a LINE-BREAK object from Org to HTML.
2738 CONTENTS is nil. INFO is a plist holding contextual information."
2739 (concat (org-html-close-tag "br" nil info) "\n"))
2741 ;;;; Link
2743 (defun org-html-inline-image-p (link info)
2744 "Non-nil when LINK is meant to appear as an image.
2745 INFO is a plist used as a communication channel. LINK is an
2746 inline image when it has no description and targets an image
2747 file (see `org-html-inline-image-rules' for more information), or
2748 if its description is a single link targeting an image file."
2749 (if (not (org-element-contents link))
2750 (org-export-inline-image-p
2751 link (plist-get info :html-inline-image-rules))
2752 (not
2753 (let ((link-count 0))
2754 (org-element-map (org-element-contents link)
2755 (cons 'plain-text org-element-all-objects)
2756 (lambda (obj)
2757 (case (org-element-type obj)
2758 (plain-text (org-string-nw-p obj))
2759 (link (if (= link-count 1) t
2760 (incf link-count)
2761 (not (org-export-inline-image-p
2762 obj (plist-get info :html-inline-image-rules)))))
2763 (otherwise t)))
2764 info t)))))
2766 (defvar org-html-standalone-image-predicate)
2767 (defun org-html-standalone-image-p (element info)
2768 "Non-nil if ELEMENT is a standalone image.
2770 INFO is a plist holding contextual information.
2772 An element or object is a standalone image when
2774 - its type is `paragraph' and its sole content, save for white
2775 spaces, is a link that qualifies as an inline image;
2777 - its type is `link' and its containing paragraph has no other
2778 content save white spaces.
2780 Bind `org-html-standalone-image-predicate' to constrain paragraph
2781 further. For example, to check for only captioned standalone
2782 images, set it to:
2784 (lambda (paragraph) (org-element-property :caption paragraph))"
2785 (let ((paragraph (case (org-element-type element)
2786 (paragraph element)
2787 (link (org-export-get-parent element)))))
2788 (and (eq (org-element-type paragraph) 'paragraph)
2789 (or (not (fboundp 'org-html-standalone-image-predicate))
2790 (funcall org-html-standalone-image-predicate paragraph))
2791 (catch 'exit
2792 (let ((link-count 0))
2793 (org-element-map (org-element-contents paragraph)
2794 (cons 'plain-text org-element-all-objects)
2795 #'(lambda (obj)
2796 (when (case (org-element-type obj)
2797 (plain-text (org-string-nw-p obj))
2798 (link (or (> (incf link-count) 1)
2799 (not (org-html-inline-image-p obj info))))
2800 (otherwise t))
2801 (throw 'exit nil)))
2802 info nil 'link)
2803 (= link-count 1))))))
2805 (defun org-html-link (link desc info)
2806 "Transcode a LINK object from Org to HTML.
2807 DESC is the description part of the link, or the empty string.
2808 INFO is a plist holding contextual information. See
2809 `org-export-data'."
2810 (let* ((home (when (plist-get info :html-link-home)
2811 (org-trim (plist-get info :html-link-home))))
2812 (use-abs-url (plist-get info :html-link-use-abs-url))
2813 (link-org-files-as-html-maybe
2814 (lambda (raw-path info)
2815 ;; Treat links to `file.org' as links to `file.html', if
2816 ;; needed. See `org-html-link-org-files-as-html'.
2817 (cond
2818 ((and (plist-get info :html-link-org-files-as-html)
2819 (string= ".org"
2820 (downcase (file-name-extension raw-path "."))))
2821 (concat (file-name-sans-extension raw-path) "."
2822 (plist-get info :html-extension)))
2823 (t raw-path))))
2824 (type (org-element-property :type link))
2825 (raw-path (org-element-property :path link))
2826 ;; Ensure DESC really exists, or set it to nil.
2827 (desc (org-string-nw-p desc))
2828 (path
2829 (cond
2830 ((member type '("http" "https" "ftp" "mailto"))
2831 (org-link-escape-browser
2832 (org-link-unescape (concat type ":" raw-path))))
2833 ((string= type "file")
2834 ;; Treat links to ".org" files as ".html", if needed.
2835 (setq raw-path
2836 (funcall link-org-files-as-html-maybe raw-path info))
2837 ;; If file path is absolute, prepend it with protocol
2838 ;; component - "file://".
2839 (cond
2840 ((file-name-absolute-p raw-path)
2841 (setq raw-path (org-export-file-uri raw-path)))
2842 ((and home use-abs-url)
2843 (setq raw-path (concat (file-name-as-directory home) raw-path))))
2844 ;; Add search option, if any. A search option can be
2845 ;; relative to a custom-id, a headline title a name,
2846 ;; a target or a radio-target.
2847 (let ((option (org-element-property :search-option link)))
2848 (if (not option) raw-path
2849 (concat raw-path
2851 (org-publish-resolve-external-link
2852 option
2853 (org-element-property :path link))))))
2854 (t raw-path)))
2855 ;; Extract attributes from parent's paragraph. HACK: Only do
2856 ;; this for the first link in parent (inner image link for
2857 ;; inline images). This is needed as long as attributes
2858 ;; cannot be set on a per link basis.
2859 (attributes-plist
2860 (let* ((parent (org-export-get-parent-element link))
2861 (link (let ((container (org-export-get-parent link)))
2862 (if (and (eq (org-element-type container) 'link)
2863 (org-html-inline-image-p link info))
2864 container
2865 link))))
2866 (and (eq (org-element-map parent 'link 'identity info t) link)
2867 (org-export-read-attribute :attr_html parent))))
2868 (attributes
2869 (let ((attr (org-html--make-attribute-string attributes-plist)))
2870 (if (org-string-nw-p attr) (concat " " attr) ""))))
2871 (cond
2872 ;; Link type is handled by a special function.
2873 ((org-export-custom-protocol-maybe link desc 'html))
2874 ;; Image file.
2875 ((and (plist-get info :html-inline-images)
2876 (org-export-inline-image-p
2877 link (plist-get info :html-inline-image-rules)))
2878 (org-html--format-image path attributes-plist info))
2879 ;; Radio target: Transcode target's contents and use them as
2880 ;; link's description.
2881 ((string= type "radio")
2882 (let ((destination (org-export-resolve-radio-link link info)))
2883 (if (not destination) desc
2884 (format "<a href=\"#%s\"%s>%s</a>"
2885 (org-export-get-reference destination info)
2886 attributes
2887 desc))))
2888 ;; Links pointing to a headline: Find destination and build
2889 ;; appropriate referencing command.
2890 ((member type '("custom-id" "fuzzy" "id"))
2891 (let ((destination (if (string= type "fuzzy")
2892 (org-export-resolve-fuzzy-link link info)
2893 (org-export-resolve-id-link link info))))
2894 (case (org-element-type destination)
2895 ;; ID link points to an external file.
2896 (plain-text
2897 (let ((fragment (concat "ID-" path))
2898 ;; Treat links to ".org" files as ".html", if needed.
2899 (path (funcall link-org-files-as-html-maybe
2900 destination info)))
2901 (format "<a href=\"%s#%s\"%s>%s</a>"
2902 path fragment attributes (or desc destination))))
2903 ;; Fuzzy link points nowhere.
2904 ((nil)
2905 (format "<i>%s</i>"
2906 (or desc
2907 (org-export-data
2908 (org-element-property :raw-link link) info))))
2909 ;; Link points to a headline.
2910 (headline
2911 (let ((href (or (org-element-property :CUSTOM_ID destination)
2912 (org-export-get-reference destination info)))
2913 ;; What description to use?
2914 (desc
2915 ;; Case 1: Headline is numbered and LINK has no
2916 ;; description. Display section number.
2917 (if (and (org-export-numbered-headline-p destination info)
2918 (not desc))
2919 (mapconcat #'number-to-string
2920 (org-export-get-headline-number
2921 destination info) ".")
2922 ;; Case 2: Either the headline is un-numbered or
2923 ;; LINK has a custom description. Display LINK's
2924 ;; description or headline's title.
2925 (or desc
2926 (org-export-data
2927 (org-element-property :title destination) info)))))
2928 (format "<a href=\"#%s\"%s>%s</a>" href attributes desc)))
2929 ;; Fuzzy link points to a target or an element.
2931 (let* ((ref (org-export-get-reference destination info))
2932 (org-html-standalone-image-predicate
2933 #'org-html--has-caption-p)
2934 (number (cond
2935 (desc nil)
2936 ((org-html-standalone-image-p destination info)
2937 (org-export-get-ordinal
2938 (org-element-map destination 'link
2939 #'identity info t)
2940 info 'link 'org-html-standalone-image-p))
2941 (t (org-export-get-ordinal
2942 destination info nil 'org-html--has-caption-p))))
2943 (desc (cond (desc)
2944 ((not number) "No description for this link")
2945 ((numberp number) (number-to-string number))
2946 (t (mapconcat #'number-to-string number ".")))))
2947 (format "<a href=\"#%s\"%s>%s</a>" ref attributes desc))))))
2948 ;; Coderef: replace link with the reference name or the
2949 ;; equivalent line number.
2950 ((string= type "coderef")
2951 (let ((fragment (concat "coderef-" (org-html-encode-plain-text path))))
2952 (format "<a href=\"#%s\"%s%s>%s</a>"
2953 fragment
2954 (format "class=\"coderef\" onmouseover=\"CodeHighlightOn(this, \
2955 '%s');\" onmouseout=\"CodeHighlightOff(this, '%s');\""
2956 fragment fragment)
2957 attributes
2958 (format (org-export-get-coderef-format path desc)
2959 (org-export-resolve-coderef path info)))))
2960 ;; External link with a description part.
2961 ((and path desc) (format "<a href=\"%s\"%s>%s</a>"
2962 (org-html-encode-plain-text path)
2963 attributes
2964 desc))
2965 ;; External link without a description part.
2966 (path (let ((path (org-html-encode-plain-text path)))
2967 (format "<a href=\"%s\"%s>%s</a>" path attributes path)))
2968 ;; No path, only description. Try to do something useful.
2969 (t (format "<i>%s</i>" desc)))))
2971 ;;;; Node Property
2973 (defun org-html-node-property (node-property contents info)
2974 "Transcode a NODE-PROPERTY element from Org to HTML.
2975 CONTENTS is nil. INFO is a plist holding contextual
2976 information."
2977 (format "%s:%s"
2978 (org-element-property :key node-property)
2979 (let ((value (org-element-property :value node-property)))
2980 (if value (concat " " value) ""))))
2982 ;;;; Paragraph
2984 (defun org-html-paragraph (paragraph contents info)
2985 "Transcode a PARAGRAPH element from Org to HTML.
2986 CONTENTS is the contents of the paragraph, as a string. INFO is
2987 the plist used as a communication channel."
2988 (let* ((parent (org-export-get-parent paragraph))
2989 (parent-type (org-element-type parent))
2990 (style '((footnote-definition " class=\"footpara\"")
2991 (org-data " class=\"footpara\"")))
2992 (attributes (org-html--make-attribute-string
2993 (org-export-read-attribute :attr_html paragraph)))
2994 (extra (or (cadr (assq parent-type style)) "")))
2995 (cond
2996 ((and (eq parent-type 'item)
2997 (not (org-export-get-previous-element paragraph info))
2998 (let ((followers (org-export-get-next-element paragraph info 2)))
2999 (and (not (cdr followers))
3000 (memq (org-element-type (car followers)) '(nil plain-list)))))
3001 ;; First paragraph in an item has no tag if it is alone or
3002 ;; followed, at most, by a sub-list.
3003 contents)
3004 ((org-html-standalone-image-p paragraph info)
3005 ;; Standalone image.
3006 (let ((caption
3007 (let ((raw (org-export-data
3008 (org-export-get-caption paragraph) info))
3009 (org-html-standalone-image-predicate
3010 'org-html--has-caption-p))
3011 (if (not (org-string-nw-p raw)) raw
3012 (concat
3013 "<span class=\"figure-number\">"
3014 (format (org-html--translate "Figure %d:" info)
3015 (org-export-get-ordinal
3016 (org-element-map paragraph 'link
3017 'identity info t)
3018 info nil 'org-html-standalone-image-p))
3019 "</span> " raw))))
3020 (label (and (org-element-property :name paragraph)
3021 (org-export-get-reference paragraph info))))
3022 (org-html--wrap-image contents info caption label)))
3023 ;; Regular paragraph.
3024 (t (format "<p%s%s>\n%s</p>"
3025 (if (org-string-nw-p attributes)
3026 (concat " " attributes) "")
3027 extra contents)))))
3029 ;;;; Plain List
3031 ;; FIXME Maybe arg1 is not needed because <li value="20"> already sets
3032 ;; the correct value for the item counter
3033 (defun org-html-begin-plain-list (type &optional arg1)
3034 "Insert the beginning of the HTML list depending on TYPE.
3035 When ARG1 is a string, use it as the start parameter for ordered
3036 lists."
3037 (case type
3038 (ordered
3039 (format "<ol class=\"org-ol\"%s>"
3040 (if arg1 (format " start=\"%d\"" arg1) "")))
3041 (unordered "<ul class=\"org-ul\">")
3042 (descriptive "<dl class=\"org-dl\">")))
3044 (defun org-html-end-plain-list (type)
3045 "Insert the end of the HTML list depending on TYPE."
3046 (case type
3047 (ordered "</ol>")
3048 (unordered "</ul>")
3049 (descriptive "</dl>")))
3051 (defun org-html-plain-list (plain-list contents info)
3052 "Transcode a PLAIN-LIST element from Org to HTML.
3053 CONTENTS is the contents of the list. INFO is a plist holding
3054 contextual information."
3055 (let* (arg1 ;; (assoc :counter (org-element-map plain-list 'item
3056 (type (org-element-property :type plain-list)))
3057 (format "%s\n%s%s"
3058 (org-html-begin-plain-list type)
3059 contents (org-html-end-plain-list type))))
3061 ;;;; Plain Text
3063 (defun org-html-convert-special-strings (string)
3064 "Convert special characters in STRING to HTML."
3065 (let ((all org-html-special-string-regexps)
3066 e a re rpl start)
3067 (while (setq a (pop all))
3068 (setq re (car a) rpl (cdr a) start 0)
3069 (while (string-match re string start)
3070 (setq string (replace-match rpl t nil string))))
3071 string))
3073 (defun org-html-encode-plain-text (text)
3074 "Convert plain text characters from TEXT to HTML equivalent.
3075 Possible conversions are set in `org-html-protect-char-alist'."
3076 (dolist (pair org-html-protect-char-alist text)
3077 (setq text (replace-regexp-in-string (car pair) (cdr pair) text t t))))
3079 (defun org-html-plain-text (text info)
3080 "Transcode a TEXT string from Org to HTML.
3081 TEXT is the string to transcode. INFO is a plist holding
3082 contextual information."
3083 (let ((output text))
3084 ;; Protect following characters: <, >, &.
3085 (setq output (org-html-encode-plain-text output))
3086 ;; Handle smart quotes. Be sure to provide original string since
3087 ;; OUTPUT may have been modified.
3088 (when (plist-get info :with-smart-quotes)
3089 (setq output (org-export-activate-smart-quotes output :html info text)))
3090 ;; Handle special strings.
3091 (when (plist-get info :with-special-strings)
3092 (setq output (org-html-convert-special-strings output)))
3093 ;; Handle break preservation if required.
3094 (when (plist-get info :preserve-breaks)
3095 (setq output
3096 (replace-regexp-in-string
3097 "\\(\\\\\\\\\\)?[ \t]*\n"
3098 (concat (org-html-close-tag "br" nil info) "\n") output)))
3099 ;; Return value.
3100 output))
3103 ;; Planning
3105 (defun org-html-planning (planning contents info)
3106 "Transcode a PLANNING element from Org to HTML.
3107 CONTENTS is nil. INFO is a plist used as a communication
3108 channel."
3109 (let ((span-fmt "<span class=\"timestamp-kwd\">%s</span> <span class=\"timestamp\">%s</span>"))
3110 (format
3111 "<p><span class=\"timestamp-wrapper\">%s</span></p>"
3112 (mapconcat
3113 'identity
3114 (delq nil
3115 (list
3116 (let ((closed (org-element-property :closed planning)))
3117 (when closed
3118 (format span-fmt org-closed-string
3119 (org-timestamp-translate closed))))
3120 (let ((deadline (org-element-property :deadline planning)))
3121 (when deadline
3122 (format span-fmt org-deadline-string
3123 (org-timestamp-translate deadline))))
3124 (let ((scheduled (org-element-property :scheduled planning)))
3125 (when scheduled
3126 (format span-fmt org-scheduled-string
3127 (org-timestamp-translate scheduled))))))
3128 " "))))
3130 ;;;; Property Drawer
3132 (defun org-html-property-drawer (property-drawer contents info)
3133 "Transcode a PROPERTY-DRAWER element from Org to HTML.
3134 CONTENTS holds the contents of the drawer. INFO is a plist
3135 holding contextual information."
3136 (and (org-string-nw-p contents)
3137 (format "<pre class=\"example\">\n%s</pre>" contents)))
3139 ;;;; Quote Block
3141 (defun org-html-quote-block (quote-block contents info)
3142 "Transcode a QUOTE-BLOCK element from Org to HTML.
3143 CONTENTS holds the contents of the block. INFO is a plist
3144 holding contextual information."
3145 (format "<blockquote>\n%s</blockquote>" contents))
3147 ;;;; Section
3149 (defun org-html-section (section contents info)
3150 "Transcode a SECTION element from Org to HTML.
3151 CONTENTS holds the contents of the section. INFO is a plist
3152 holding contextual information."
3153 (let ((parent (org-export-get-parent-headline section)))
3154 ;; Before first headline: no container, just return CONTENTS.
3155 (if (not parent) contents
3156 ;; Get div's class and id references.
3157 (let* ((class-num (+ (org-export-get-relative-level parent info)
3158 (1- (plist-get info :html-toplevel-hlevel))))
3159 (section-number
3160 (and (org-export-numbered-headline-p parent info)
3161 (mapconcat
3162 #'number-to-string
3163 (org-export-get-headline-number parent info) "-"))))
3164 ;; Build return value.
3165 (format "<div class=\"outline-text-%d\" id=\"text-%s\">\n%s</div>"
3166 class-num
3167 (or (org-element-property :CUSTOM_ID parent)
3168 section-number
3169 (org-export-get-reference parent info))
3170 (or contents ""))))))
3172 ;;;; Radio Target
3174 (defun org-html-radio-target (radio-target text info)
3175 "Transcode a RADIO-TARGET object from Org to HTML.
3176 TEXT is the text of the target. INFO is a plist holding
3177 contextual information."
3178 (let ((ref (org-export-get-reference radio-target info)))
3179 (org-html--anchor ref text nil info)))
3181 ;;;; Special Block
3183 (defun org-html-special-block (special-block contents info)
3184 "Transcode a SPECIAL-BLOCK element from Org to HTML.
3185 CONTENTS holds the contents of the block. INFO is a plist
3186 holding contextual information."
3187 (let* ((block-type (org-element-property :type special-block))
3188 (contents (or contents ""))
3189 (html5-fancy (and (org-html--html5-fancy-p info)
3190 (member block-type org-html-html5-elements)))
3191 (attributes (org-export-read-attribute :attr_html special-block)))
3192 (unless html5-fancy
3193 (let ((class (plist-get attributes :class)))
3194 (setq attributes (plist-put attributes :class
3195 (if class (concat class " " block-type)
3196 block-type)))))
3197 (setq attributes (org-html--make-attribute-string attributes))
3198 (when (not (equal attributes ""))
3199 (setq attributes (concat " " attributes)))
3200 (if html5-fancy
3201 (format "<%s%s>\n%s</%s>" block-type attributes
3202 contents block-type)
3203 (format "<div%s>\n%s\n</div>" attributes contents))))
3205 ;;;; Src Block
3207 (defun org-html-src-block (src-block contents info)
3208 "Transcode a SRC-BLOCK element from Org to HTML.
3209 CONTENTS holds the contents of the item. INFO is a plist holding
3210 contextual information."
3211 (if (org-export-read-attribute :attr_html src-block :textarea)
3212 (org-html--textarea-block src-block)
3213 (let ((lang (org-element-property :language src-block))
3214 (caption (org-export-get-caption src-block))
3215 (code (org-html-format-code src-block info))
3216 (label (let ((lbl (and (org-element-property :name src-block)
3217 (org-export-get-reference src-block info))))
3218 (if lbl (format " id=\"%s\"" lbl) ""))))
3219 (if (not lang) (format "<pre class=\"example\"%s>\n%s</pre>" label code)
3220 (format
3221 "<div class=\"org-src-container\">\n%s%s\n</div>"
3222 (if (not caption) ""
3223 (format "<label class=\"org-src-name\">%s</label>"
3224 (org-export-data caption info)))
3225 (format "\n<pre class=\"src src-%s\"%s>%s</pre>" lang label code))))))
3227 ;;;; Statistics Cookie
3229 (defun org-html-statistics-cookie (statistics-cookie contents info)
3230 "Transcode a STATISTICS-COOKIE object from Org to HTML.
3231 CONTENTS is nil. INFO is a plist holding contextual information."
3232 (let ((cookie-value (org-element-property :value statistics-cookie)))
3233 (format "<code>%s</code>" cookie-value)))
3235 ;;;; Strike-Through
3237 (defun org-html-strike-through (strike-through contents info)
3238 "Transcode STRIKE-THROUGH from Org to HTML.
3239 CONTENTS is the text with strike-through markup. INFO is a plist
3240 holding contextual information."
3241 (format
3242 (or (cdr (assq 'strike-through (plist-get info :html-text-markup-alist)))
3243 "%s")
3244 contents))
3246 ;;;; Subscript
3248 (defun org-html-subscript (subscript contents info)
3249 "Transcode a SUBSCRIPT object from Org to HTML.
3250 CONTENTS is the contents of the object. INFO is a plist holding
3251 contextual information."
3252 (format "<sub>%s</sub>" contents))
3254 ;;;; Superscript
3256 (defun org-html-superscript (superscript contents info)
3257 "Transcode a SUPERSCRIPT object from Org to HTML.
3258 CONTENTS is the contents of the object. INFO is a plist holding
3259 contextual information."
3260 (format "<sup>%s</sup>" contents))
3262 ;;;; Table Cell
3264 (defun org-html-table-cell (table-cell contents info)
3265 "Transcode a TABLE-CELL element from Org to HTML.
3266 CONTENTS is nil. INFO is a plist used as a communication
3267 channel."
3268 (let* ((table-row (org-export-get-parent table-cell))
3269 (table (org-export-get-parent-table table-cell))
3270 (cell-attrs
3271 (if (not (plist-get info :html-table-align-individual-fields)) ""
3272 (format (if (and (boundp 'org-html-format-table-no-css)
3273 org-html-format-table-no-css)
3274 " align=\"%s\"" " class=\"org-%s\"")
3275 (org-export-table-cell-alignment table-cell info)))))
3276 (when (or (not contents) (string= "" (org-trim contents)))
3277 (setq contents "&#xa0;"))
3278 (cond
3279 ((and (org-export-table-has-header-p table info)
3280 (= 1 (org-export-table-row-group table-row info)))
3281 (let ((header-tags (plist-get info :html-table-header-tags)))
3282 (concat "\n" (format (car header-tags) "col" cell-attrs)
3283 contents
3284 (cdr header-tags))))
3285 ((and (plist-get info :html-table-use-header-tags-for-first-column)
3286 (zerop (cdr (org-export-table-cell-address table-cell info))))
3287 (let ((header-tags (plist-get info :html-table-header-tags)))
3288 (concat "\n" (format (car header-tags) "row" cell-attrs)
3289 contents
3290 (cdr header-tags))))
3291 (t (let ((data-tags (plist-get info :html-table-data-tags)))
3292 (concat "\n" (format (car data-tags) cell-attrs)
3293 contents
3294 (cdr data-tags)))))))
3296 ;;;; Table Row
3298 (defun org-html-table-row (table-row contents info)
3299 "Transcode a TABLE-ROW element from Org to HTML.
3300 CONTENTS is the contents of the row. INFO is a plist used as a
3301 communication channel."
3302 ;; Rules are ignored since table separators are deduced from
3303 ;; borders of the current row.
3304 (when (eq (org-element-property :type table-row) 'standard)
3305 (let* ((rowgroup-number (org-export-table-row-group table-row info))
3306 (row-number (org-export-table-row-number table-row info))
3307 (start-rowgroup-p
3308 (org-export-table-row-starts-rowgroup-p table-row info))
3309 (end-rowgroup-p
3310 (org-export-table-row-ends-rowgroup-p table-row info))
3311 ;; `top-row-p' and `end-rowgroup-p' are not used directly
3312 ;; but should be set so that `org-html-table-row-tags' can
3313 ;; use them (see the docstring of this variable.)
3314 (top-row-p (and (equal start-rowgroup-p '(top))
3315 (equal end-rowgroup-p '(below top))))
3316 (bottom-row-p (and (equal start-rowgroup-p '(above))
3317 (equal end-rowgroup-p '(bottom above))))
3318 (rowgroup-tags
3319 (cond
3320 ;; Case 1: Row belongs to second or subsequent rowgroups.
3321 ((not (= 1 rowgroup-number))
3322 '("<tbody>" . "\n</tbody>"))
3323 ;; Case 2: Row is from first rowgroup. Table has >=1 rowgroups.
3324 ((org-export-table-has-header-p
3325 (org-export-get-parent-table table-row) info)
3326 '("<thead>" . "\n</thead>"))
3327 ;; Case 2: Row is from first and only row group.
3328 (t '("<tbody>" . "\n</tbody>")))))
3329 (concat
3330 ;; Begin a rowgroup?
3331 (when start-rowgroup-p (car rowgroup-tags))
3332 ;; Actual table row
3333 (concat "\n" (eval (car (plist-get info :html-table-row-tags)))
3334 contents
3335 "\n"
3336 (eval (cdr (plist-get info :html-table-row-tags))))
3337 ;; End a rowgroup?
3338 (when end-rowgroup-p (cdr rowgroup-tags))))))
3340 ;;;; Table
3342 (defun org-html-table-first-row-data-cells (table info)
3343 "Transcode the first row of TABLE.
3344 INFO is a plist used as a communication channel."
3345 (let ((table-row
3346 (org-element-map table 'table-row
3347 (lambda (row)
3348 (unless (eq (org-element-property :type row) 'rule) row))
3349 info 'first-match))
3350 (special-column-p (org-export-table-has-special-column-p table)))
3351 (if (not special-column-p) (org-element-contents table-row)
3352 (cdr (org-element-contents table-row)))))
3354 (defun org-html-table--table.el-table (table info)
3355 "Format table.el tables into HTML.
3356 INFO is a plist used as a communication channel."
3357 (when (eq (org-element-property :type table) 'table.el)
3358 (require 'table)
3359 (let ((outbuf (with-current-buffer
3360 (get-buffer-create "*org-export-table*")
3361 (erase-buffer) (current-buffer))))
3362 (with-temp-buffer
3363 (insert (org-element-property :value table))
3364 (goto-char 1)
3365 (re-search-forward "^[ \t]*|[^|]" nil t)
3366 (table-generate-source 'html outbuf))
3367 (with-current-buffer outbuf
3368 (prog1 (org-trim (buffer-string))
3369 (kill-buffer) )))))
3371 (defun org-html-table (table contents info)
3372 "Transcode a TABLE element from Org to HTML.
3373 CONTENTS is the contents of the table. INFO is a plist holding
3374 contextual information."
3375 (case (org-element-property :type table)
3376 ;; Case 1: table.el table. Convert it using appropriate tools.
3377 (table.el (org-html-table--table.el-table table info))
3378 ;; Case 2: Standard table.
3380 (let* ((caption (org-export-get-caption table))
3381 (number (org-export-get-ordinal
3382 table info nil #'org-html--has-caption-p))
3383 (attributes
3384 (org-html--make-attribute-string
3385 (org-combine-plists
3386 (and (org-element-property :name table)
3387 (list :id (org-export-get-reference table info)))
3388 (and (not (org-html-html5-p info))
3389 (plist-get info :html-table-attributes))
3390 (org-export-read-attribute :attr_html table))))
3391 (alignspec
3392 (if (and (boundp 'org-html-format-table-no-css)
3393 org-html-format-table-no-css)
3394 "align=\"%s\"" "class=\"org-%s\""))
3395 (table-column-specs
3396 (function
3397 (lambda (table info)
3398 (mapconcat
3399 (lambda (table-cell)
3400 (let ((alignment (org-export-table-cell-alignment
3401 table-cell info)))
3402 (concat
3403 ;; Begin a colgroup?
3404 (when (org-export-table-cell-starts-colgroup-p
3405 table-cell info)
3406 "\n<colgroup>")
3407 ;; Add a column. Also specify its alignment.
3408 (format "\n%s"
3409 (org-html-close-tag
3410 "col" (concat " " (format alignspec alignment)) info))
3411 ;; End a colgroup?
3412 (when (org-export-table-cell-ends-colgroup-p
3413 table-cell info)
3414 "\n</colgroup>"))))
3415 (org-html-table-first-row-data-cells table info) "\n")))))
3416 (format "<table%s>\n%s\n%s\n%s</table>"
3417 (if (equal attributes "") "" (concat " " attributes))
3418 (if (not caption) ""
3419 (format (if (plist-get info :html-table-caption-above)
3420 "<caption class=\"t-above\">%s</caption>"
3421 "<caption class=\"t-bottom\">%s</caption>")
3422 (concat
3423 "<span class=\"table-number\">"
3424 (format (org-html--translate "Table %d:" info) number)
3425 "</span> " (org-export-data caption info))))
3426 (funcall table-column-specs table info)
3427 contents)))))
3429 ;;;; Target
3431 (defun org-html-target (target contents info)
3432 "Transcode a TARGET object from Org to HTML.
3433 CONTENTS is nil. INFO is a plist holding contextual
3434 information."
3435 (let ((ref (org-export-get-reference target info)))
3436 (org-html--anchor ref nil nil info)))
3438 ;;;; Timestamp
3440 (defun org-html-timestamp (timestamp contents info)
3441 "Transcode a TIMESTAMP object from Org to HTML.
3442 CONTENTS is nil. INFO is a plist holding contextual
3443 information."
3444 (let ((value (org-html-plain-text (org-timestamp-translate timestamp) info)))
3445 (format "<span class=\"timestamp-wrapper\"><span class=\"timestamp\">%s</span></span>"
3446 (replace-regexp-in-string "--" "&#x2013;" value))))
3448 ;;;; Underline
3450 (defun org-html-underline (underline contents info)
3451 "Transcode UNDERLINE from Org to HTML.
3452 CONTENTS is the text with underline markup. INFO is a plist
3453 holding contextual information."
3454 (format (or (cdr (assq 'underline (plist-get info :html-text-markup-alist)))
3455 "%s")
3456 contents))
3458 ;;;; Verbatim
3460 (defun org-html-verbatim (verbatim contents info)
3461 "Transcode VERBATIM from Org to HTML.
3462 CONTENTS is nil. INFO is a plist holding contextual
3463 information."
3464 (format (or (cdr (assq 'verbatim (plist-get info :html-text-markup-alist))) "%s")
3465 (org-html-encode-plain-text (org-element-property :value verbatim))))
3467 ;;;; Verse Block
3469 (defun org-html-verse-block (verse-block contents info)
3470 "Transcode a VERSE-BLOCK element from Org to HTML.
3471 CONTENTS is verse block contents. INFO is a plist holding
3472 contextual information."
3473 ;; Replace each newline character with line break. Also replace
3474 ;; each blank line with a line break.
3475 (setq contents (replace-regexp-in-string
3476 "^ *\\\\\\\\$" (format "%s\n" (org-html-close-tag "br" nil info))
3477 (replace-regexp-in-string
3478 "\\(\\\\\\\\\\)?[ \t]*\n"
3479 (format "%s\n" (org-html-close-tag "br" nil info)) contents)))
3480 ;; Replace each white space at beginning of a line with a
3481 ;; non-breaking space.
3482 (while (string-match "^[ \t]+" contents)
3483 (let* ((num-ws (length (match-string 0 contents)))
3484 (ws (let (out) (dotimes (i num-ws out)
3485 (setq out (concat out "&#xa0;"))))))
3486 (setq contents (replace-match ws nil t contents))))
3487 (format "<p class=\"verse\">\n%s</p>" contents))
3490 ;;; Filter Functions
3492 (defun org-html-final-function (contents backend info)
3493 "Filter to indent the HTML and convert HTML entities."
3494 (with-temp-buffer
3495 (insert contents)
3496 (set-auto-mode t)
3497 (if (plist-get info :html-indent)
3498 (indent-region (point-min) (point-max)))
3499 (buffer-substring-no-properties (point-min) (point-max))))
3502 ;;; End-user functions
3504 ;;;###autoload
3505 (defun org-html-export-as-html
3506 (&optional async subtreep visible-only body-only ext-plist)
3507 "Export current buffer to an HTML buffer.
3509 If narrowing is active in the current buffer, only export its
3510 narrowed part.
3512 If a region is active, export that region.
3514 A non-nil optional argument ASYNC means the process should happen
3515 asynchronously. The resulting buffer should be accessible
3516 through the `org-export-stack' interface.
3518 When optional argument SUBTREEP is non-nil, export the sub-tree
3519 at point, extracting information from the headline properties
3520 first.
3522 When optional argument VISIBLE-ONLY is non-nil, don't export
3523 contents of hidden elements.
3525 When optional argument BODY-ONLY is non-nil, only write code
3526 between \"<body>\" and \"</body>\" tags.
3528 EXT-PLIST, when provided, is a property list with external
3529 parameters overriding Org default settings, but still inferior to
3530 file-local settings.
3532 Export is done in a buffer named \"*Org HTML Export*\", which
3533 will be displayed when `org-export-show-temporary-export-buffer'
3534 is non-nil."
3535 (interactive)
3536 (org-export-to-buffer 'html "*Org HTML Export*"
3537 async subtreep visible-only body-only ext-plist
3538 (lambda () (set-auto-mode t))))
3540 ;;;###autoload
3541 (defun org-html-convert-region-to-html ()
3542 "Assume the current region has org-mode syntax, and convert it to HTML.
3543 This can be used in any buffer. For example, you can write an
3544 itemized list in org-mode syntax in an HTML buffer and use this
3545 command to convert it."
3546 (interactive)
3547 (org-export-replace-region-by 'html))
3549 ;;;###autoload
3550 (defun org-html-export-to-html
3551 (&optional async subtreep visible-only body-only ext-plist)
3552 "Export current buffer to a HTML file.
3554 If narrowing is active in the current buffer, only export its
3555 narrowed part.
3557 If a region is active, export that region.
3559 A non-nil optional argument ASYNC means the process should happen
3560 asynchronously. The resulting file should be accessible through
3561 the `org-export-stack' interface.
3563 When optional argument SUBTREEP is non-nil, export the sub-tree
3564 at point, extracting information from the headline properties
3565 first.
3567 When optional argument VISIBLE-ONLY is non-nil, don't export
3568 contents of hidden elements.
3570 When optional argument BODY-ONLY is non-nil, only write code
3571 between \"<body>\" and \"</body>\" tags.
3573 EXT-PLIST, when provided, is a property list with external
3574 parameters overriding Org default settings, but still inferior to
3575 file-local settings.
3577 Return output file's name."
3578 (interactive)
3579 (let* ((extension (concat "." (or (plist-get ext-plist :html-extension)
3580 org-html-extension
3581 "html")))
3582 (file (org-export-output-file-name extension subtreep))
3583 (org-export-coding-system org-html-coding-system))
3584 (org-export-to-file 'html file
3585 async subtreep visible-only body-only ext-plist)))
3587 ;;;###autoload
3588 (defun org-html-publish-to-html (plist filename pub-dir)
3589 "Publish an org file to HTML.
3591 FILENAME is the filename of the Org file to be published. PLIST
3592 is the property list for the given project. PUB-DIR is the
3593 publishing directory.
3595 Return output file name."
3596 (org-publish-org-to 'html filename
3597 (concat "." (or (plist-get plist :html-extension)
3598 org-html-extension
3599 "html"))
3600 plist pub-dir))
3603 (provide 'ox-html)
3605 ;; Local variables:
3606 ;; generated-autoload-file: "org-loaddefs.el"
3607 ;; End:
3609 ;;; ox-html.el ends here