Hi, Attached to this e-mail, you can find my patch that add, in the HTML export backend, missing options-alist keywords and `#+OPTIONS`. I added them when it's possible. Also, for options with a keyword, I defined the behavior for when their keyword is set multiple times in an Org-mode buffer.
This patch only update the manual for backend option that where already described in the manual. As requested by Ihor Radchenko. Also, the `:html-extension` option have no new keyword due to a bug that prevent making it modifiable via the options-alist of the export backend. # Motivation Some HTML export backend options have no keyword or `#+OPTIONS:` key defined. So, it's not easily possible to set theses options directly on an Org-mode buffer. Best regards ------- Gendre Sébastien
From 213b8f84bca7d55a860e0ad5a99da9e988412105 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Gendre?= <[email protected]> Date: Mon, 20 Oct 2025 23:33:50 +0200 Subject: [PATCH] lisp/ox-html.el: Add missing keywords and `#+OPTIONS:` in backend options-alist * lisp/ox-html.el (html): Into the HTML backend options-alist, add missing keywords and `#+OPTIONS:` when possible. Also for options with a keyword defined, set the multi-keywords behavior if possible. * doc/org-manual.org (HTML preamble and postamble, Links in HTML export, Tables in HTML export, Images in HTML export, Math formatting in HTML export, CSS support): Only update to manual sections where the modified options are already described * etc/ORG-NEWS (ox-html: Headline self links can be enabled from an Org-mode file): Replace this section with new section "More options can be set from an Org-mode file". This new section talk about all the new keywords or `#+OPTIONS:` added. (ox-html: More options can be set from an Org-mode file): List all the new keywords and `#+OPTIONS:` added. Also list the options with keyword that accept its keyword being set multiple times in the same buffer. In the HTML backend, some options defined in the options-alist have no keyword or `#+OPTIONS:` defined. I changed that. For options with keyword, I also defined the multi-keyword behavior. As requested on the mailing list, I only updated the manual for options that where already described. A complete refresh of the manual about all the HTML backend options is needed, on a separate patch. Due to a bug, `:html-extension` option cannot be set in buffer. So, no keyword added for it. Also, `:html-divs` are to complex to be defined by an `#+OPTIONS:` or a keyword. It will need a modification on another patch. TINYCHANGE --- doc/org-manual.org | 57 ++++++++++++++++++++++--------- etc/ORG-NEWS | 78 ++++++++++++++++++++++++++++++++++++++---- lisp/ox-html.el | 84 +++++++++++++++++++++++++++++----------------- 3 files changed, 165 insertions(+), 54 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index ff5a569d4..fb316c4c9 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -13609,11 +13609,18 @@ to return a string upon execution. The HTML exporter inserts this string in the preamble. The HTML exporter does not insert a preamble if ~org-html-preamble~ is set ~nil~. +In an org-mode buffer, you can set the preamble value with the option +~html-preamble~. Use it preferably to set values like ~t~, ~nil~, ~auto~ or +even a function. To set your preamble as a string, use the keyword +~#+HTML_PREAMBLE~. You can use it multiple times to set a multi-lines +string. + The above also applies to ~org-html-postamble~ and -~org-html-postamble-format~. In addition, ~org-html-postamble~ can be -set to ~auto~ (its default value), which makes the HTML exporter build -a postamble from looking up author's name, email address, creator's -name, and date. +~org-html-postamble-format~. In addition, ~org-html-postamble~ can be set +to ~auto~ (its default value), which makes the HTML exporter build a +postamble from looking up author's name, email address, creator's +name, and date. And as for preamble, postamble value can be set in +buffer with ~html-postamble~ option or with ~#+HTML_POSTAMBLE~ keyword. *** Exporting to minimal HTML @@ -13714,6 +13721,10 @@ disabled, the HTML export backend substitutes the ID-based links in the HTML output. For more about linking files when publishing to a directory, see [[*Publishing links]]. +Alternatively, you can disable the automatic path translation in +buffer level by using the option ~html-link-org-files-as-html~: +: #+OPTIONS: html-link-org-files-as-html:nil + Org files can also have special directives to the HTML export backend. For example, by using =#+ATTR_HTML= lines to specify new format attributes to ~<a>~ or ~<img>~ tags. This example shows @@ -13728,6 +13739,7 @@ changing the link's title and style: *** Tables in HTML export :PROPERTIES: :DESCRIPTION: How to modify the formatting of tables. +:ID: d2a6f5c3-0c65-4898-9515-828aaec7ef85 :END: #+cindex: tables, in HTML #+vindex: org-export-html-table-tag @@ -13753,12 +13765,16 @@ Additional options for customizing tables for HTML export. #+vindex: org-html-table-align-individual-fields Non-~nil~ attaches style attributes for alignment to each table - field. + field. Can also bet set with buffer option + ~html-table-align-individual-fields~. + : #+options: html-table-align-individual-fields:t - ~org-html-table-caption-above~ :: #+vindex: org-html-table-caption-above - Non-~nil~ places caption string at the beginning of the table. + Non-~nil~ places caption string at the beginning of the table. Can + also be set with buffer option ~html-table-caption-above~. + : #+options: html-table-caption-above:t - ~org-html-table-data-tags~ :: @@ -13783,7 +13799,10 @@ Additional options for customizing tables for HTML export. - ~org-html-table-use-header-tags-for-first-column~ :: #+vindex: org-html-table-use-header-tags-for-first-column - Non-~nil~ formats column one in tables with header tags. + Non-~nil~ formats column one in tables with header tags. Can also be + set with buffer option + ~org-html-table-use-header-tags-for-first-column~. + : #+options: org-html-table-use-header-tags-for-first-column:t *** Images in HTML export :PROPERTIES: @@ -13798,9 +13817,11 @@ HTML inline images and HTML clickable image links. #+vindex: org-html-inline-images When the link in the Org file has no description, the HTML export backend by default in-lines that image. For example: -=[[file:myimg.jpg]]= is in-lined, while =[[file:myimg.jpg][the image]]= links to the text, -=the image=. For more details, see the variable -~org-html-inline-images~. +=[[file:myimg.jpg]]= is in-lined, while =[[file:myimg.jpg][the image]]= +links to the text, =the image=. You can set the variable +~org-html-inline-images~ to ~nil~ to have no in-lines images and only +links. You can also use the buffer option ~html-inline-images~. +: #+options: html-inline-images:nil On the other hand, if the description part of the Org link is itself another link, such as =file:= or =https:= URL pointing to an image, the @@ -13863,7 +13884,9 @@ To use a local copy of MathJax, use =path= option: #+vindex: org-html-mathjax-template See the docstring of ~org-html-mathjax-options~ for all supported variables. The MathJax template can be configured via -~org-html-mathjax-template~. +~org-html-mathjax-template~ or via the buffer keyword +~#+HTML_MATHJAX_TEMPLATE~. This keyword can be set multiple time in +the buffer, to set a multi-lines template. If you prefer, you can also request that LaTeX fragments are processed into small images that will be inserted into the browser page. Before @@ -13914,6 +13937,7 @@ line. *** CSS support :PROPERTIES: :DESCRIPTION: Changing the appearance of the output. +:ID: 242c9f6f-2d02-4d3d-82e9-60ceb8dfaf11 :END: #+cindex: CSS, for HTML export #+cindex: HTML export, CSS @@ -13922,11 +13946,12 @@ line. #+vindex: org-export-html-tag-class-prefix You can modify the CSS style definitions for the exported file. The HTML exporter assigns the following special CSS classes[fn:: If the -classes on TODO keywords and tags lead to conflicts, use the variables -~org-html-todo-kwd-class-prefix~ and ~org-html-tag-class-prefix~ to -make them unique.] to appropriate parts of the document---your style -specifications may change these, in addition to any of the standard -classes like for headlines, tables, etc. +classes on TODO keywords and tags lead to conflicts: Use the variables +~org-html-todo-kwd-class-prefix~ and ~org-html-tag-class-prefix~, or the +buffer options ~html-todo-kwd-class-prefix~ and ~html-tag-class-prefix~, +to make them unique.] to appropriate parts of the document---your +style specifications may change these, in addition to any of the +standard classes like for headlines, tables, etc. | ~p.author~ | author information, including email | | ~p.date~ | publishing date | diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 87fbf8f06..9062d6f20 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -352,15 +352,79 @@ slide to specific animation steps. This text will be displayed on animation step 2 and later. #+END_SRC -*** ox-html: Headline self links can be enabled from an Org-mode file - -Previously HTML export could add, to each headline, a link to itself. -To enable it, you had to use the variable -~org-html-self-link-headlines~. - -Now, it's also possible to enable it per Org-mode file by adding: +*** ox-html: More options can be set from an Org-mode file + +Starting from this version of Org-mode, more HTML exporter options +could be set in an Org-mode file with a KEYWORD or with `#+OPTIONS:'. + +| Option name | Keyword | Option key | Default value | +|------------------------------------------------+----------------------------------+-----------------------------------------------+---------------------------------------------------| +| ~:html-postamble~ | ~HTML_POSTAMBLE~ | ~html-postamble~ | ~org-html-postamble~ | +| ~:html-allow-name-attribute-in-anchors~ | | ~html-name-attr-in-anchors~ | ~org-html-allow-name-attribute-in-anchors~ | +| ~:html-self-link-headlines~ | | ~html-self-link-headlines~ | ~org-html-self-link-headlines~ | +| ~:html-checkbox-type~ | | ~html-checkbox-type~ | ~org-html-checkbox-type~ | +| ~:html-footnote-format~ | ~HTML_FOOTNOTE_FORMAT~ | | ~org-html-footnote-format~ | +| ~:html-footnote-separator~ | ~HTML_FOOTNOTE_SEPARATOR~ | | ~org-html-footnote-separator~ | +| ~:html-footnotes-section~ | ~HTML_FOOTNOTES_SECTION~ | | ~org-html-footnotes-section~ | +| ~:html-home/up-format~ | ~HTML_HOME/UP_FORMAT~ | | ~org-html-home/up-format~ | +| ~:html-indent~ | | ~html-indent~ | ~org-html-indent~ | +| ~:html-infojs-template~ | ~HTML_INFOJS_TEMPLATE~ | | ~org-html-infojs-template~ | +| ~:html-link-org-files-as-html~ | | ~html-link-org-files-as-html~ | ~org-html-link-org-files-as-html~ | +| ~:html-mathjax-template~ | ~HTML_MATHJAX_TEMPLATE~ | | ~org-html-mathjax-template~ | +| ~:html-metadata-timestamp-format~ | ~HTML_METADATA_TIMESTAMP_FORMAT~ | | ~org-html-metadata-timestamp-format~ | +| ~:html-table-align-individual-fields~ | | ~html-table-align-individual-fields~ | ~org-html-table-align-individual-fields~ | +| ~:html-table-caption-above~ | | ~html-table-caption-above~ | ~org-html-table-caption-above~ | +| ~:html-table-use-header-tags-for-first-column~ | | ~html-table-use-header-tags-for-first-column~ | ~org-html-table-use-header-tags-for-first-column~ | +| ~:html-tag-class-prefix~ | | ~html-tag-class-prefix~ | ~org-html-tag-class-prefix~ | +| ~:html-todo-kwd-class-prefix~ | | ~html-todo-kwd-class-prefix~ | ~org-html-todo-kwd-class-prefix~ | +| ~:html-toplevel-hlevel~ | | ~html-toplevel-hlevel~ | ~org-html-toplevel-hlevel~ | +| ~:html-use-infojs~ | | ~html-use-infojs~ | ~org-html-use-infojs~ | +| ~:html-validation-link~ | ~HTML_VALIDATION_LINK~ | | ~org-html-validation-link~ | +| ~:html-inline-images~ | | ~html-inline-images~ | ~org-html-inline-images~ | +| ~:html-table-row-open-tag~ | ~HTML_TABLE_ROW_OPEN_TAG~ | | ~org-html-table-row-open-tag~ | +| ~:html-table-row-close-tag~ | ~HTML_TABLE_ROW_CLOSE_TAG~ | | ~org-html-table-row-close-tag~ | +| ~:html-xml-declaration~ | ~HTML_XML_DECLARATION~ | | ~org-html-xml-declaration~ | +| ~:html-wrap-src-lines~ | | ~html-wrap-src-lines~ | ~org-html-wrap-src-lines~ | + + +=Option key= are to be used like this: : #+OPTIONS: html-self-link-headlines:t +To know which value you can use, you can found them on the manual or, if +not, in the default variable value. + +Some export options, that can be set with a keyword, now accept to +have its keyword set multiple times in the same org-mode file. If +it's the case, each values are concatenate and separated with a +newline. + +Here is the list of option with this behavior modified: + +| Option name | Keyword | +|-----------------------------+----------------------------| +| ~:html-postamble~ | ~HTML_POSTAMBLE~ | +| ~:html-preamble~ | ~HTML_PREAMBLE~ | +| ~:html-footnotes-section~ | ~HTML_FOOTNOTES_SECTION~ | +| ~:html-home/up-format~ | ~HTML_HOME/UP_FORMAT~ | +| ~:html-infojs-template~ | ~HTML_INFOJS_TEMPLATE~ | +| ~:html-mathjax-template~ | ~HTML_MATHJAX_TEMPLATE~ | +| ~:html-validation-link~ | ~HTML_VALIDATION_LINK~ | +| ~:html-table-row-open-tag~ | ~HTML_TABLE_ROW_OPEN_TAG~ | +| ~:html-table-row-close-tag~ | ~HTML_TABLE_ROW_CLOSE_TAG~ | +| ~:html-xml-declaration~ | ~HTML_XML_DECLARATION~ | +| ~:creator~ | ~CREATOR~ | + + +Example of usage: +#+begin_example org +,#+HTML_POSTAMBLE: <p> +,#+HTML_POSTAMBLE: Postamble of my web page. +,#+HTML_POSTAMBLE: </p> +,#+HTML_POSTAMBLE: <p> +,#+HTML_POSTAMBLE: Licence of my website: GNU FDL +,#+HTML_POSTAMBLE: </p> +#+end_example + *** ox-latex: Table of contents generation has been fixed and augmented diff --git a/lisp/ox-html.el b/lisp/ox-html.el index 2f014de91..0d72344d8 100644 --- a/lisp/ox-html.el +++ b/lisp/ox-html.el @@ -124,71 +124,93 @@ (:description "DESCRIPTION" nil nil newline) (:keywords "KEYWORDS" nil nil space) (:html-html5-fancy nil "html5-fancy" org-html-html5-fancy) - (:html-link-use-abs-url nil "html-link-use-abs-url" org-html-link-use-abs-url) + (:html-link-use-abs-url + nil "html-link-use-abs-url" org-html-link-use-abs-url) (:html-link-home "HTML_LINK_HOME" nil org-html-link-home) (:html-link-up "HTML_LINK_UP" nil org-html-link-up) (:html-mathjax "HTML_MATHJAX" nil "" space) - (:html-equation-reference-format "HTML_EQUATION_REFERENCE_FORMAT" nil org-html-equation-reference-format t) - (:html-postamble nil "html-postamble" org-html-postamble) - (:html-preamble nil "html-preamble" org-html-preamble) + (:html-equation-reference-format + "HTML_EQUATION_REFERENCE_FORMAT" nil org-html-equation-reference-format t) + (:html-postamble "HTML_POSTAMBLE" "html-postamble" org-html-postamble newline) + (:html-preamble "HTML_PREAMBLE" "html-preamble" org-html-preamble newline) (:html-head "HTML_HEAD" nil org-html-head newline) (:html-head-extra "HTML_HEAD_EXTRA" nil org-html-head-extra newline) (:subtitle "SUBTITLE" nil nil parse) (:html-head-include-default-style nil "html-style" org-html-head-include-default-style) - (:html-head-include-scripts nil "html-scripts" org-html-head-include-scripts) + (:html-head-include-scripts + nil "html-scripts" org-html-head-include-scripts) (:html-allow-name-attribute-in-anchors - nil nil org-html-allow-name-attribute-in-anchors) + nil "html-name-attr-in-anchors" org-html-allow-name-attribute-in-anchors) (:html-divs nil nil org-html-divs) - (:html-checkbox-type nil nil org-html-checkbox-type) + (:html-checkbox-type nil "html-checkbox-type" org-html-checkbox-type) + ;; Due to a bug, :html-extension option cannot be set in buffer (:html-extension nil nil org-html-extension) - (:html-footnote-format nil nil org-html-footnote-format) - (:html-footnote-separator nil nil org-html-footnote-separator) - (:html-footnotes-section nil nil org-html-footnotes-section) + (:html-footnote-format "HTML_FOOTNOTE_FORMAT" nil org-html-footnote-format) + (:html-footnote-separator + "HTML_FOOTNOTE_SEPARATOR" nil org-html-footnote-separator) + (:html-footnotes-section + "HTML_FOOTNOTES_SECTION" nil org-html-footnotes-section newline) (:html-format-drawer-function nil nil org-html-format-drawer-function) (:html-format-headline-function nil nil org-html-format-headline-function) (:html-format-inlinetask-function nil nil org-html-format-inlinetask-function) - (:html-home/up-format nil nil org-html-home/up-format) - (:html-indent nil nil org-html-indent) + (:html-home/up-format "HTML_HOME/UP_FORMAT" nil org-html-home/up-format newline) + (:html-indent nil "html-indent" org-html-indent) (:html-infojs-options nil nil org-html-infojs-options) - (:html-infojs-template nil nil org-html-infojs-template) + (:html-infojs-template "HTML_INFOJS_TEMPLATE" nil org-html-infojs-template newline) (:html-inline-image-rules nil nil org-html-inline-image-rules) - (:html-link-org-files-as-html nil nil org-html-link-org-files-as-html) + (:html-link-org-files-as-html + nil "html-link-org-files-as-html" org-html-link-org-files-as-html) (:html-mathjax-options nil nil org-html-mathjax-options) - (:html-mathjax-template nil nil org-html-mathjax-template) - (:html-metadata-timestamp-format nil nil org-html-metadata-timestamp-format) + (:html-mathjax-template + "HTML_MATHJAX_TEMPLATE" nil org-html-mathjax-template newline) + (:html-metadata-timestamp-format + "HTML_METADATA_TIMESTAMP_FORMAT" nil org-html-metadata-timestamp-format) (:html-postamble-format nil nil org-html-postamble-format) (:html-preamble-format nil nil org-html-preamble-format) - (:html-prefer-user-labels nil nil org-html-prefer-user-labels) - (:html-self-link-headlines nil "html-self-link-headlines" org-html-self-link-headlines) + (:html-prefer-user-labels + nil "html-prefer-user-labels" org-html-prefer-user-labels) + (:html-self-link-headlines + nil "html-self-link-headlines" org-html-self-link-headlines) (:html-table-align-individual-fields - nil nil org-html-table-align-individual-fields) - (:html-table-caption-above nil nil org-html-table-caption-above) + nil "html-table-align-individual-fields" + org-html-table-align-individual-fields) + (:html-table-caption-above + nil "html-table-caption-above" org-html-table-caption-above) (:html-table-data-tags nil nil org-html-table-data-tags) (:html-table-header-tags nil nil org-html-table-header-tags) (:html-table-use-header-tags-for-first-column - nil nil org-html-table-use-header-tags-for-first-column) - (:html-tag-class-prefix nil nil org-html-tag-class-prefix) + nil "html-table-use-header-tags-for-first-column" + org-html-table-use-header-tags-for-first-column) + (:html-tag-class-prefix + nil "html-tag-class-prefix" org-html-tag-class-prefix) (:html-text-markup-alist nil nil org-html-text-markup-alist) - (:html-todo-kwd-class-prefix nil nil org-html-todo-kwd-class-prefix) - (:html-toplevel-hlevel nil nil org-html-toplevel-hlevel) + (:html-todo-kwd-class-prefix + nil "html-todo-kwd-class-prefix" org-html-todo-kwd-class-prefix) + (:html-toplevel-hlevel nil "html-toplevel-hlevel" org-html-toplevel-hlevel) + ;; To enable infojs from in-buffer, set INFOJS_OPT buffer option (:html-use-infojs nil nil org-html-use-infojs) - (:html-validation-link nil nil org-html-validation-link) + (:html-validation-link + "HTML_VALIDATION_LINK" nil org-html-validation-link newline) (:html-viewport nil nil org-html-viewport) - (:html-inline-images nil nil org-html-inline-images) + (:html-inline-images nil "html-inline-images" org-html-inline-images) (:html-table-attributes nil nil org-html-table-default-attributes) - (:html-table-row-open-tag nil nil org-html-table-row-open-tag) - (:html-table-row-close-tag nil nil org-html-table-row-close-tag) - (:html-xml-declaration nil nil org-html-xml-declaration) - (:html-wrap-src-lines nil nil org-html-wrap-src-lines) + (:html-table-row-open-tag + "HTML_TABLE_ROW_OPEN_TAG" nil org-html-table-row-open-tag newline) + (:html-table-row-close-tag + "HTML_TABLE_ROW_CLOSE_TAG" nil org-html-table-row-close-tag newline) + (:html-xml-declaration + "HTML_XML_DECLARATION" nil org-html-xml-declaration newline) + (:html-wrap-src-lines + nil "html-wrap-src-lines" org-html-wrap-src-lines) (:html-klipsify-src nil nil org-html-klipsify-src) (:html-klipse-css nil nil org-html-klipse-css) (:html-klipse-js nil nil org-html-klipse-js) (:html-klipse-selection-script nil nil org-html-klipse-selection-script) (:infojs-opt "INFOJS_OPT" nil nil) ;; Redefine regular options. - (:creator "CREATOR" nil org-html-creator-string) + (:creator "CREATOR" nil org-html-creator-string newline) (:with-latex nil "tex" org-html-with-latex) ;; Retrieve LaTeX header for fragments. (:latex-header "LATEX_HEADER" nil nil newline))) -- 2.50.1
signature.asc
Description: PGP signature
