Hi, Sorry for the delay. End of year was very busy.
Attached to this e-mail is the fixed patch, rebased to the latest commit of the `main' today.
From 2830b763c93e2fd7f52f3dc6a06b720dea08d1e7 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. --- doc/org-manual.org | 54 +++++++++++++++++++++--------- etc/ORG-NEWS | 78 +++++++++++++++++++++++++++++++++++++++---- lisp/ox-html.el | 83 +++++++++++++++++++++++++++++----------------- 3 files changed, 162 insertions(+), 53 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 8f917a57e..69661601a 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -13621,11 +13621,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-line +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 @@ -13726,6 +13733,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 @@ -13770,12 +13781,15 @@ 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 be set as: + : #+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~ :: @@ -13800,7 +13814,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: @@ -13815,9 +13832,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-lined images and only +links. You can also use the buffer option ~html-inline-images~. +: #+options: html-inline-images:nil #+vindex: org-html-inline-image-rules On the other hand, if the description part of the Org link is itself @@ -13882,7 +13901,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 times in +the buffer, to set a multi-line 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 @@ -13941,11 +13962,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 2e1f79f8c..6bc4b0a89 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -394,15 +394,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, the 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 ae700b6e6..da1be3c27 100644 --- a/lisp/ox-html.el +++ b/lisp/ox-html.el @@ -119,64 +119,87 @@ (: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 + ;; Discussion about this bug here: https://list.orgmode.org/[email protected]/ (: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) -- 2.52.0
For more details: Ihor Radchenko <[email protected]> writes: > Note that the patch is exceeding the maximum contribution size we can > accept without copyright assignment. Would you consider it? See > https://orgmode.org/worg/org-contribute.html#copyright If I remember correctly, I already have signed a copyright assignment. But it was some time ago and I don't remember if I completed it. I will contact the FSF to know and come back about it. >> * 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 > > *described. Fixed. >> In the HTML backend, some options defined in the options-alist have no >> keyword or `#+OPTIONS:` defined. I changed that. For options with > > Double space between sentences :) Fixed. >> +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 > > I do not think that you can make it a function. I have tested and you can specify a function name as a value for `html-preamble' and `html-postamble' options. Do I replace "function" by "function name" to be more precise ? >> +~#+HTML_PREAMBLE~. You can use it multiple times to set a multi-lines >> +string. > > *multi-line string. Fixed. >> +name, and date. And as for preamble, postamble value can be set in > > *, as for preamble, Fixed. >> :PROPERTIES: >> :DESCRIPTION: How to modify the formatting of tables. >> +:ID: d2a6f5c3-0c65-4898-9515-828aaec7ef85 >> :END: > > Please get rid of these stray IDs. Done. >> + field. Can also bet set with buffer option >> + ~html-table-align-individual-fields~. >> + : #+options: html-table-align-individual-fields:t > > *bet -> be > > "buffer option" reads weird. Maybe just say > "Can also be set as > : #+options: ..." > Same in other cases. Done. >> +=[[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 > > *in-lined Fixed. >> +~#+HTML_MATHJAX_TEMPLATE~. This keyword can be set multiple time in > > *times Fixed. >> +the buffer, to set a multi-lines template. > > *multi-line template Fixed. >> :DESCRIPTION: Changing the appearance of the output. >> +:ID: 242c9f6f-2d02-4d3d-82e9-60ceb8dfaf11 >> :END: > > Stray ID. Removed. >> -*** 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: > > You accidentally removed this record. I rewritten the section "ox-html: Headline self links can be enabled from an Org-mode file" into a new section "ox-html: More options can be set from an Org-mode file". The previous section only describe the new option "org-html-self-link-headlines" while the new replacement section describe all the new options and keywords. >> +To know which value you can use, you can found them on the manual or, if >> +not, in the default variable value. > > What do you mean here? All these new buffer options and keywords accept different values. To avoid listing all of them in `etc/ORG-NEWS', I redirect the users to the manual and, when it's not written in the manual, to the values accepted by the default variable of these buffer options and keywords. As described in their doc string. >> +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. > > *the values are concatenated and... Fixed. >> + ;; Due to a bug, :html-extension option cannot be set in buffer >> (:html-extension nil nil org-html-extension) > > Please link to the orgmode.org/list/... discussion for reference. Done. >> ;; Redefine regular options. >> - (:creator "CREATOR" nil org-html-creator-string) >> + (:creator "CREATOR" nil org-html-creator-string newline) > > This is a global option applicable to other backends. ox-html modifies > it to use different default value, but otherwise ought to keep the same > behavior. If you want to change :creator in ox-html, please also do in > ox.html. I restored the previous behavior.
signature.asc
Description: PGP signature
