%s
")
(italic . "%s")
(strike-through . "%s
"))
"Alist of HTML expressions to convert text markup.
The key must be a symbol among `bold', `code', `italic',
`strike-through', `underline' and `verbatim'. The value is
a formatting string to wrap fontified text with.
If no association can be found for a given markup, text will be
returned as-is."
:group 'org-export-html
:version "24.4"
:package-version '(Org . "8.0")
:type '(alist :key-type (symbol :tag "Markup type")
:value-type (string :tag "Format string"))
:options '(bold code italic strike-through underline verbatim))
(defcustom org-html-indent nil
"Non-nil means to indent the generated HTML.
Warning: non-nil may break indentation of source code blocks."
:group 'org-export-html
:version "24.4"
:package-version '(Org . "8.0")
:type 'boolean)
;;;; Drawers
(defcustom org-html-format-drawer-function (lambda (_name contents) contents)
"Function called to format a drawer in HTML code.
The function must accept two parameters:
NAME the drawer name, like \"LOGBOOK\"
CONTENTS the contents of the drawer.
The function should return the string to be exported.
For example, the variable could be set to the following function
in order to mimic default behavior:
The default value simply returns the value of CONTENTS."
:group 'org-export-html
:version "24.4"
:package-version '(Org . "8.0")
:type 'function)
;;;; Footnotes
(defcustom org-html-footnotes-section "[X]
")
(off . "[ ]
")
(trans . "[-]
")))
(html .
((on . "")
(off . "")
(trans . ""))))
"Alist of checkbox types.
The cdr of each entry is an alist list three checkbox types for
HTML export: `on', `off' and `trans'.
The choices are:
`unicode' Unicode characters (HTML entities)
`ascii' ASCII characters
`html' HTML checkboxes
Note that only the ascii characters implement tri-state
checkboxes. The other two use the `off' checkbox for `trans'.")
(defcustom org-html-checkbox-type 'ascii
"The type of checkboxes to use for HTML export.
See `org-html-checkbox-types' for for the values used for each
option."
:group 'org-export-html
:version "24.4"
:package-version '(Org . "8.0")
:type '(choice
(const :tag "ASCII characters" ascii)
(const :tag "Unicode characters" unicode)
(const :tag "HTML checkboxes" html)))
(defcustom org-html-metadata-timestamp-format "%Y-%m-%d %a %H:%M"
"Format used for timestamps in preamble, postamble and metadata.
See `format-time-string' for more information on its components."
:group 'org-export-html
:version "24.4"
:package-version '(Org . "8.0")
:type 'string)
;;;; Template :: Mathjax
(defcustom org-html-mathjax-options
'((path "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML" )
(scale "100")
(align "center")
(font "TeX")
(linebreaks "false")
(autonumber "AMS")
(indent "0em")
(multlinewidth "85%")
(tagindent ".8em")
(tagside "right"))
"Options for MathJax setup.
Alist of the following elements. All values are strings.
path The path to MathJax.
scale Scaling with HTML-CSS, MathML and SVG output engines.
align How to align display math: left, center, or right.
font The font to use with HTML-CSS and SVG output. As of MathJax 2.5
the following values are understood: \"TeX\", \"STIX-Web\",
\"Asana-Math\", \"Neo-Euler\", \"Gyre-Pagella\",
\"Gyre-Termes\", and \"Latin-Modern\".
linebreaks Let MathJax perform automatic linebreaks. Valid values
are \"true\" and \"false\".
indent If align is not center, how far from the left/right side?
Valid values are \"left\" and \"right\"
multlinewidth The width of the multline environment.
autonumber How to number equations. Valid values are \"None\",
\"all\" and \"AMS Math\".
tagindent The amount tags are indented.
tagside Which side to show tags/labels on. Valid values are
\"left\" and \"right\"
You can also customize this for each buffer, using something like
#+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
For further information about MathJax options, see the MathJax documentation:
http://docs.mathjax.org/"
:group 'org-export-html
:package-version '(Org . "8.3")
:type '(list :greedy t
(list :tag "path (the path from where to load MathJax.js)"
(const :format " " path) (string))
(list :tag "scale (scaling for the displayed math)"
(const :format " " scale) (string))
(list :tag "align (alignment of displayed equations)"
(const :format " " align) (string))
(list :tag "font (used to display math)"
(const :format " " font)
(choice (const "TeX")
(const "STIX-Web")
(const "Asana-Math")
(const "Neo-Euler")
(const "Gyre-Pagella")
(const "Gyre-Termes")
(const "Latin-Modern")))
(list :tag "linebreaks (automatic line-breaking)"
(const :format " " linebreaks)
(choice (const "true")
(const "false")))
(list :tag "autonumber (when should equations be numbered)"
(const :format " " autonumber)
(choice (const "AMS")
(const "None")
(const "All")))
(list :tag "indent (indentation with left or right alignment)"
(const :format " " indent) (string))
(list :tag "multlinewidth (width to use for the multline environment)"
(const :format " " multlinewidth) (string))
(list :tag "tagindent (the indentation of tags from left or right)"
(const :format " " tagindent) (string))
(list :tag "tagside (location of tags)"
(const :format " " tagside)
(choice (const "left")
(const "right")))))
(defcustom org-html-mathjax-template
"
"
"The MathJax template. See also `org-html-mathjax-options'."
:group 'org-export-html
:type 'string)
;;;; Template :: Postamble
(defcustom org-html-postamble 'auto
"Non-nil means insert a postamble in HTML export.
When set to `auto', check against the
`org-export-with-author/email/creator/date' variables to set the
content of the postamble. When set to a string, use this string
as the postamble. When t, insert a string as defined by the
formatting string in `org-html-postamble-format'.
When set to a function, apply this function and insert the
returned string. The function takes the property list of export
options as its only argument.
Setting :html-postamble in publishing projects will take
precedence over this variable."
:group 'org-export-html
:type '(choice (const :tag "No postamble" nil)
(const :tag "Auto postamble" auto)
(const :tag "Default formatting string" t)
(string :tag "Custom formatting string")
(function :tag "Function (must return a string)")))
(defcustom org-html-postamble-format
'(("en" "Date: %d
%c
%v
")) "Alist of languages and format strings for the HTML postamble. The first element of each list is the language code, as used for the LANGUAGE keyword. See `org-export-default-language'. The second element of each list is a format string to format the postamble itself. This format string can contain these elements: %t stands for the title. %s stands for the subtitle. %a stands for the author's name. %e stands for the author's email. %d stands for the date. %c will be replaced by `org-html-creator-string'. %v will be replaced by `org-html-validation-link'. %T will be replaced by the export time. %C will be replaced by the last modification time. If you need to use a \"%\" character, you need to escape it like that: \"%%\"." :group 'org-export-html :type '(repeat (list (string :tag "Language") (string :tag "Format string")))) (defcustom org-html-validation-link "Validate" "Link to HTML validation service." :group 'org-export-html :type 'string) (defcustom org-html-creator-string (format "Emacs %s (Org mode %s)" emacs-version (if (fboundp 'org-version) (org-version) "unknown version")) "Information about the creator of the HTML document. This option can also be set on with the CREATOR keyword." :group 'org-export-html :version "24.4" :package-version '(Org . "8.0") :type '(string :tag "Creator string")) ;;;; Template :: Preamble (defcustom org-html-preamble t "Non-nil means insert a preamble in HTML export. When t, insert a string as defined by the formatting string in `org-html-preamble-format'. When set to a string, use this formatting string instead (see `org-html-postamble-format' for an example of such a formatting string). When set to a function, apply this function and insert the returned string. The function takes the property list of export options as its only argument. Setting :html-preamble in publishing projects will take precedence over this variable." :group 'org-export-html :type '(choice (const :tag "No preamble" nil) (const :tag "Default preamble" t) (string :tag "Custom formatting string") (function :tag "Function (must return a string)"))) (defcustom org-html-preamble-format '(("en" "")) "Alist of languages and format strings for the HTML preamble. The first element of each list is the language code, as used for the LANGUAGE keyword. See `org-export-default-language'. The second element of each list is a format string to format the preamble itself. This format string can contain these elements: %t stands for the title. %s stands for the subtitle. %a stands for the author's name. %e stands for the author's email. %d stands for the date. %c will be replaced by `org-html-creator-string'. %v will be replaced by `org-html-validation-link'. %T will be replaced by the export time. %C will be replaced by the last modification time. If you need to use a \"%\" character, you need to escape it like that: \"%%\". See the default value of `org-html-postamble-format' for an example." :group 'org-export-html :type '(repeat (list (string :tag "Language") (string :tag "Format string")))) (defcustom org-html-link-up "" "Where should the \"UP\" link of exported HTML pages lead?" :group 'org-export-html :type '(string :tag "File or URL")) (defcustom org-html-link-home "" "Where should the \"HOME\" link of exported HTML pages lead?" :group 'org-export-html :type '(string :tag "File or URL")) (defcustom org-html-link-use-abs-url nil "Should we prepend relative links with HTML_LINK_HOME?" :group 'org-export-html :version "24.4" :package-version '(Org . "8.1") :type 'boolean) (defcustom org-html-home/up-format "" "Snippet used to insert the HOME and UP links. This is a format string, the first %s will receive the UP link, the second the HOME link. If both `org-html-link-up' and `org-html-link-home' are empty, the entire snippet will be ignored." :group 'org-export-html :type 'string) ;;;; Template :: Scripts (defcustom org-html-head-include-scripts t "Non-nil means include the JavaScript snippets in exported HTML files. The actual script is defined in `org-html-scripts' and should not be modified." :group 'org-export-html :version "24.4" :package-version '(Org . "8.0") :type 'boolean) ;;;; Template :: Styles (defcustom org-html-head-include-default-style t "Non-nil means include the default style in exported HTML files. The actual style is defined in `org-html-style-default' and should not be modified. Use `org-html-head' to use your own style information." :group 'org-export-html :version "24.4" :package-version '(Org . "8.0") :type 'boolean) ;;;###autoload (put 'org-html-head-include-default-style 'safe-local-variable 'booleanp) (defcustom org-html-head "" "Org-wide head definitions for exported HTML files. This variable can contain the full HTML structure to provide a style, including the surrounding HTML tags. You can consider including definitions for the following classes: title, todo, done, timestamp, timestamp-kwd, tag, target. For example, a valid value would be: If you want to refer to an external style, use something like As the value of this option simply gets inserted into the HTML header, you can use it to add any arbitrary text to the header. You can set this on a per-file basis using #+HTML_HEAD:, or for publication projects using the :html-head property." :group 'org-export-html :version "24.4" :package-version '(Org . "8.0") :type 'string) ;;;###autoload (put 'org-html-head 'safe-local-variable 'stringp) (defcustom org-html-head-extra "" "More head information to add in the HTML output. You can set this on a per-file basis using #+HTML_HEAD_EXTRA:, or for publication projects using the :html-head-extra property." :group 'org-export-html :version "24.4" :package-version '(Org . "8.0") :type 'string) ;;;###autoload (put 'org-html-head-extra 'safe-local-variable 'stringp) ;;;; Template :: Viewport (defcustom org-html-viewport '((width "device-width") (initial-scale "1") (minimum-scale "") (maximum-scale "") (user-scalable "")) "Viewport options for mobile-optimized sites. The following values are recognized width Size of the viewport. initial-scale Zoom level when the page is first loaded. minimum-scale Minimum allowed zoom level. maximum-scale Maximum allowed zoom level. user-scalable Whether zoom can be changed. The viewport meta tag is inserted if this variable is non-nil. See the following site for a reference: https://developer.mozilla.org/en-US/docs/Mozilla/Mobile/Viewport_meta_tag" :group 'org-export-html :version "26.1" :package-version '(Org . "8.3") :type '(choice (const :tag "Disable" nil) (list :tag "Enable" (list :tag "Width of viewport" (const :format " " width) (choice (const :tag "unset" "") (string))) (list :tag "Initial scale" (const :format " " initial-scale) (choice (const :tag "unset" "") (string))) (list :tag "Minimum scale/zoom" (const :format " " minimum-scale) (choice (const :tag "unset" "") (string))) (list :tag "Maximum scale/zoom" (const :format " " maximum-scale) (choice (const :tag "unset" "") (string))) (list :tag "User scalable/zoomable" (const :format " " user-scalable) (choice (const :tag "unset" "") (const "true") (const "false")))))) ;; Handle source code blocks with Klipse (defcustom org-html-klipsify-src nil "When non-nil, source code blocks are editable in exported presentation." :group 'org-export-html :package-version '(Org . "9.1") :type 'boolean) (defcustom org-html-klipse-css "https://storage.googleapis.com/app.klipse.tech/css/codemirror.css" "Location of the codemirror CSS file for use with klipse." :group 'org-export-html :package-version '(Org . "9.1") :type 'string) (defcustom org-html-klipse-js "https://storage.googleapis.com/app.klipse.tech/plugin_prod/js/klipse_plugin.min.js" "Location of the klipse javascript file." :group 'org-export-html :type 'string) (defcustom org-html-klipse-selection-script "window.klipse_settings = {selector_eval_html: '.src-html', selector_eval_js: '.src-js', selector_eval_python_client: '.src-python', selector_eval_scheme: '.src-scheme', selector: '.src-clojure', selector_eval_ruby: '.src-ruby'};" "Javascript snippet to activate klipse." :group 'org-export-html :package-version '(Org . "9.1") :type 'string) (defcustom org-html-keep-old-src nil "When non-nil, useinstead of." :group 'org-export-html :package-version '(Org . "9.1") :type 'boolean) ;;;; Todos (defcustom org-html-todo-kwd-class-prefix "" "Prefix to class names for TODO keywords. Each TODO keyword gets a class given by the keyword itself, with this prefix. The default prefix is empty because it is nice to just use the keyword as a class name. But if you get into conflicts with other, existing CSS classes, then this prefix can be very useful." :group 'org-export-html :type 'string) ;;; Internal Functions (defun org-html-xhtml-p (info) (let ((dt (downcase (plist-get info :html-doctype)))) (string-match-p "xhtml" dt))) (defun org-html-html5-p (info) (let ((dt (downcase (plist-get info :html-doctype)))) (member dt '("html5" "xhtml5" "")))) (defun org-html--html5-fancy-p (info) "Non-nil when exporting to HTML5 with fancy elements. INFO is the current state of the export process, as a plist." (and (plist-get info :html-html5-fancy) (org-html-html5-p info))) (defun org-html-close-tag (tag attr info) "Return close-tag for string TAG. ATTR specifies additional attributes. INFO is a property list containing current export state." (concat "<" tag (org-string-nw-p (concat " " attr)) (if (org-html-xhtml-p info) " />" ">"))) (defun org-html-doctype (info) "Return correct HTML doctype tag. INFO is a plist used as a communication channel. Doctype tag is extracted from `org-html-doctype-alist', or the literal value of :html-doctype from INFO if :html-doctype is not found in the alist." (let ((dt (plist-get info :html-doctype))) (or (cdr (assoc dt org-html-doctype-alist)) dt))) (defun org-html--make-attribute-string (attributes) "Return a list of attributes, as a string. ATTRIBUTES is a plist where values are either strings or nil. An attribute with a nil value will be omitted from the result." (let (output) (dolist (item attributes (mapconcat 'identity (nreverse output) " ")) (cond ((null item) (pop output)) ((symbolp item) (push (substring (symbol-name item) 1) output)) (t (let ((key (car output)) (value (replace-regexp-in-string "\"" """ (org-html-encode-plain-text item)))) (setcar output (format "%s=\"%s\"" key value)))))))) (defun org-html--wrap-image (contents info &optional caption label) "Wrap CONTENTS string within an appropriate environment for images. INFO is a plist used as a communication channel. When optional arguments CAPTION and LABEL are given, use them for caption and \"id\" attribute." (let ((html5-fancy (org-html--html5-fancy-p info))) (format (if html5-fancy "\n" "\n
\n%s%s\n") ;; ID. (if (org-string-nw-p label) (format " id=\"%s\"" label) "") ;; Contents. (if html5-fancy contents (format "%s
" contents)) ;; Caption. (if (not (org-string-nw-p caption)) "" (format (if html5-fancy "\n%s " "\n%s
") caption))))) (defun org-html--format-image (source attributes info) "Return \"img\" tag with given SOURCE and ATTRIBUTES. SOURCE is a string specifying the location of the image. ATTRIBUTES is a plist, as returned by `org-export-read-attribute'. INFO is a plist used as a communication channel." (if (string= "svg" (file-name-extension source)) (org-html--svg-image source attributes info) (org-html-close-tag "img" (org-html--make-attribute-string (org-combine-plists (list :src source :alt (if (string-match-p "^ltxpng/" source) (org-html-encode-plain-text (org-find-text-property-in-string 'org-latex-src source)) (file-name-nondirectory source))) attributes)) info))) (defun org-html--svg-image (source attributes info) "Return \"object\" embedding svg file SOURCE with given ATTRIBUTES. INFO is a plist used as a communication channel. The special attribute \"fallback\" can be used to specify a fallback image file to use if the object embedding is not supported. CSS class \"org-svg\" is assigned as the class of the object unless a different class is specified with an attribute." (let ((fallback (plist-get attributes :fallback)) (attrs (org-html--make-attribute-string (org-combine-plists ;; Remove fallback attribute, which is not meant to ;; appear directly in the attributes string, and ;; provide a default class if none is set. '(:class "org-svg") attributes '(:fallback nil))))) (format "" source attrs (if fallback (org-html-close-tag "img" (format "src=\"%s\" %s" fallback attrs) info) "Sorry, your browser does not support SVG.")))) (defun org-html--textarea-block (element) "Transcode ELEMENT into a textarea block. ELEMENT is either a src block or an example block." (let* ((code (car (org-export-unravel-code element))) (attr (org-export-read-attribute :attr_html element))) (format "\n\n
" (or (plist-get attr :width) 80) (or (plist-get attr :height) (org-count-lines code)) code))) (defun org-html--has-caption-p (element &optional _info) "Non-nil when ELEMENT has a caption affiliated keyword. INFO is a plist used as a communication channel. This function is meant to be used as a predicate for `org-export-get-ordinal' or a value to `org-html-standalone-image-predicate'." (org-element-property :caption element)) ;;;; Table (defun org-html-htmlize-region-for-paste (beg end) "Convert the region between BEG and END to HTML, using htmlize.el. This is much like `htmlize-region-for-paste', only that it uses the settings define in the org-... variables." (let* ((htmlize-output-type org-html-htmlize-output-type) (htmlize-css-name-prefix org-html-htmlize-font-prefix) (htmlbuf (htmlize-region beg end))) (unwind-protect (with-current-buffer htmlbuf (buffer-substring (plist-get htmlize-buffer-places 'content-start) (plist-get htmlize-buffer-places 'content-end))) (kill-buffer htmlbuf)))) ;;;###autoload (defun org-html-htmlize-generate-css () "Create the CSS for all font definitions in the current Emacs session. Use this to create face definitions in your CSS style file that can then be used by code snippets transformed by htmlize. This command just produces a buffer that contains class definitions for all faces used in the current Emacs session. You can copy and paste the ones you need into your CSS file. If you then set `org-html-htmlize-output-type' to `css', calls to the function `org-html-htmlize-region-for-paste' will produce code that uses these same face definitions." (interactive) (or (require 'htmlize nil t) (error "Please install htmlize from https://github.com/hniksic/emacs-htmlize")) (and (get-buffer "*html*") (kill-buffer "*html*")) (with-temp-buffer (let ((fl (face-list)) (htmlize-css-name-prefix "org-") (htmlize-output-type 'css) f i) (while (setq f (pop fl) i (and f (face-attribute f :inherit))) (when (and (symbolp f) (or (not i) (not (listp i)))) (insert (org-add-props (copy-sequence "1") nil 'face f)))) (htmlize-region (point-min) (point-max)))) (pop-to-buffer-same-window "*html*") (goto-char (point-min)) (if (re-search-forward "