Release notes | Org mode

We no longer aim to support third-party python-mode.el implementation of Python REPL. Only the built-in python.el will be supported from now on.

We still keep the old, partially broken, code in ob-python.el for the time being. It will be removed in the next release.

See https://orgmode.org/list/87r0yk7bx8.fsf@localhost for more details.

The old element cache code has been refactored. Emacs does not hang anymore when the cache is enabled.

When cache is enabled, org-element-at-point for headings is guaranteed to return valid :parent property. The highest-level headings contain new org-data element as their parent.

The new org-data element provides properties from top-level property drawer, buffer-global category, and :path property containing file path for file Org buffers.

The new cache still need to be tested extensively. Please, report any warning coming from element cache. If you see warnings regularly, it would be helpful to set org-element--cache-self-verify to 'backtrace and provide the backtrace to Org mailing list.

The cache state is saved between Emacs sessions. Enabled by default.

The cache persistence can be controlled via org-element-cache-persistent.

The old folding backend used in Org is poorly scalable when the file size increases beyond few Mbs. The symptoms usually include slow cursor motion, especially in long-running Emacs sessions.

A new optimised folding backend is now available, and enabled by default. To disable it, put the following to the Emacs config before loading Org:

(setq org-fold-core-style 'overlays)

Even more performance optimisation can be enabled by customising org-fold-core--optimise-for-huge-buffers. However, this option may be dangerous. Please, read the variable docstring carefully to understand the possible consequences.

When org-fold-core-style is set to text-properties, several new features will become available and several notable changes will happen to the Org behaviour. The new features and changes are listed below.

Org now uses MathJax 3 by default instead of MathJax 2. During HTML exports, Org automatically converts all legacy MathJax 2 options to the corresponding MathJax 3+ options, except for the path option in which now must point to a file containing MathJax version 3 or later. The new Org does not work with the legacy MathJax 2.

Further, if you need to use a non-default font or linebreaks (now overflow), then the path must point to MathJax 4 or later.

See the updated org-html-mathjax-options for more details.

MathJax 3, a ground-up rewrite of MathJax 2 came out in 2019. The new version brings modularity, better and faster rendering, improved LaTeX support, and more.

For more information about new features, see:

https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html https://docs.mathjax.org/en/latest/upgrading/whats-new-3.1.html https://docs.mathjax.org/en/latest/upgrading/whats-new-3.2.html

MathJax 3 comes with useful extensions. For instance, you can typeset calculus with the physics extension or chemistry with the mhchem extension, like in LaTeX.

Note that the Org manual does not discuss loading of MathJax extensions via +HTML_MATHJAX anymore. It has never worked anyway. To actually load extensions, consult the official documentation:

https://docs.mathjax.org/en/latest/input/tex/extensions.html

Lastly, MathJax 3 changed the default JavaScript content delivery network (CDN) provider from CloudFlare to jsDelivr. You can find the new terms of service, including the privacy policy, at https://www.jsdelivr.com/terms.

:step clock table parameter can now be set to quarter.

Links to other published Org files are automatically converted to the corresponding html links. Now, this feature is also available when links point to encrypted Org files, like [[file:foo.org.gpg::Heading]].

org-edit-special and org-insert-structure-template now handle comment blocks.

See New command org-edit-comment-block to edit comment block at point.

A new alist variable to control how properties are combined.

If a property is specified multiple times with a +, like

:PROPERTIES:
:EXPORT_FILE_NAME: some/path
:EXPORT_FILE_NAME+: to/file
:END:

the old behavior was to always combine them with a single space (some/path to/file). For the new variable, the car of each item in the alist should be either a list of property names or a regular expression, while the cdr should be the separator to use when combining that property.

The default value for the separator is a single space, if none of the provided items in the alist match a given property.

For example, in order to combine EXPORT_FILE_NAME properties with a forward slash /, one can use

(setq org-property-separators '((("EXPORT_FILE_NAME") . "/")))

The example above would then produce the property value some/path/to/file.

The library stores variable data in org-persist-directory (set to XDG cache dir by default).

The entry points are org-persist-register, org-persist-unregister, org-persist-read, and org-persist-read-all. Storing circular structures is supported. Storing references between different variables is also supported (see :inherit key in org-persist-register).

The library permits storing buffer-local variables. Such variables are linked to the buffer text, file inode, and file path.

The :options attribute allows adding an optional argument with a list of various table options (between brackets in LaTeX export), since certain tabular environments, such as longtblr of the tabularray LaTeX package, provides this structure.

The :compact attribute allows exporting multiple description list items to one @item command and one or more @itemx commands. This feature can also be enabled for all description lists in a file using the compact-itemx export option, or globally using the org-texinfo-compact-itemx variable.

Items in a description list that begin with Function:, Variable: or certain related prefixes are converted using Texinfo definition commands.

:noweb-prefix can be set to no to prevent the prefix characters from being repeated when expanding a multiline noweb reference.

:noweb can be set to strip-tangle to strip the noweb syntax references before tangling.

When org-latex-src-block-backend is set to engraved, engrave-faces-latex from engrave-faces is used to transcode source blocks to LaTeX. This requires the fvextra, float, and (by default, but not necessarily) tcolorbox LaTeX packages be installed. It uses Emacs' font-lock information, and so tends to produce results superior to Minted or Listings.

#+include: FILE will now accept URLs as the file.

The block type in org-structure-template-alist is not case-sensitive. When the block type starts from the upper case, structure template will now insert #+BEGIN_TYPE. Previously, lower-case #+begin_type was inserted unconditionally.

Latex tables can now be exported to the latex tabbing environment tabbing environment]]. This is done by adding #+ATTR_LATEX: :mode tabbing at the top of the table. The default column width is set to 1/n times the latex textwidth, where n is the number of columns. This behaviour can be changed by supplying a :align parameter.

The tabbing environment can be useful when generating simple tables which can be span multiple pages and when table cells are allowed to overflow.

The "csl" citation export processor now supports nocite style citations that add items to the printed bibliography without visible references in the text. Using the key * in a nocite citation, for instance,

[cite/n:@*]

includes all available items in the printed bibliography.

The "csl" export processor now also supports sub-bibliographies that show only a subset of the references based on some criterion. For example,

#+print_bibliography: :type book :keyword ai

prints a sub-bibliography containing the book entries with ai among their keywords.

The :filetitle option for clock tables can be set to t to show org file title (set by #+title:) in the File column instead of the file name. For example:

#+BEGIN: clocktable :scope agenda :maxlevel 2 :block thisweek :filetitle t

If a file does not have a title, the table will show the file name instead.

The org-md-toplevel-hlevel customization variable sets the heading level used for top level headings, much like how org-html-toplevel-hlevel sets the heading level used for top level headings in HTML export.

Use the header argument :var x=code-block[] or

#+CALL: fn(x=code-block[])

to pass the contents of a named code block as a string argument.

The new property ORG-IMAGE-ACTUAL-WIDTH can override the global variable org-image-actual-width value for inline images display width.

New org-cycle-hook function org-cycle-display-inline-images for auto-displaying inline images in the visible parts of the subtree. This behavior is controlled by new custom option org-cycle-inline-images-display.

This provides a proper counterpart to org-babel-pre-tangle-hook, as org-babel-post-tangle-hook is run per-tangle-destination. org-babel-tangle-finished-hook is just run once after the post tangle hooks.

The :backend header argument on clojure code blocks can override the value of org-babel-clojure-backend. For example:

(range 2)

Unlike :results none, the return value of code blocks called with :results discard header argument is always nil. Org does not attempt to analyze the results and simply returns nil. This can be useful when the code block is used for side effects only but generates large outputs that may be slow to analyze for Org.

Setting org-refile-use-outline-path to 'title will show title instead of the file name in refile targets. If the document do not have a title, the filename will be used, similar to 'file option.

Setting org-agenda-show-outline-path to 'title will show title instead of the file name at the beginning of the outline. The title of the document can be set by special keyword #+title:.

These settings allow users to define prefixes for exported summary lines in ICS exports. The customization can be used to disable the prefixes completely or make them a little bit more verbose (e.g. "Deadline: " instead of the default "DL: ").

The same settings can also be applied via corresponding exporter options: :icalendar-scheduled-summary-prefix, :icalendar-deadline-summary-prefix

Previously, all the drawers were always folded when opening an Org file. This only had an effect on the drawers outside folded headlines. The drawers inside folded headlines were re-folded because org-cycle-hide-drawers was present inside org-cycle-hook.

With the new folding backend, running org-cycle-hide-drawers is no longer needed if all the drawers are truly folded on startup: Folding state of the drawers is now preserved when cycling headline visibility. However, this has an unwanted effect when a user does not want the drawers to be folded (see this bug report).

The new custom setting gives more control over initial folding state of the drawers. When set to nil (default is t), the drawers are not folded on startup.

The folding state can also be controlled on per-file basis using STARTUP keyword:

#+startup: hidedrawers
#+startup: nohidedrawers

The new setting, when set to non-nil, makes Org create alarm at the event time when the alarm time is set to 0. The default value is nil – do not create alarms at the event time.

A function to collect the document title from the org-mode buffer.

org-fold-show-entry now accepts an optional argument HIDE-DRAWERS. When the argument is non-nil, the function folds all the drawers inside entry. This was the default previously.

Now, org-fold-show-entry does not fold drawers by default.

As the contents of comments blocks is not parsed as Org markup, the headlines and keywords inside should be escaped, similar to src blocks, example blocks, and export blocks. This in inconvenient to do manually and org-edit-special is usually advised to edit text in such kind of blocks.

Now, comment block editing is also supported via this new function.

When element cache is enabled, the new function provides the best possible performance to map across large Org buffers.

It is recommended to provide :next-re and :fail-re parameters for best speed.

Diagnostic information about execution speed can be provided according to org-element--cache-map-statistics and org-element--cache-map-statistics-threshold.

org-scan-tags and tag views in agenda utilise the new function.

This function is like org-element-at-point, but it does not try to update the cache and does not guarantee correct :parent properties for headline elements.

This function is faster than org-element-at-point when used together with frequent buffer edits.

org-in-archived-heading-p, org-in-commented-heading-p, org-up-heading-safe, org-end-of-subtree, org-goto-first-child, org-back-to-heading, org-entry-get-with-inheritance, and org-narrow-to-subtree all accept Org element as an extra optional argument.

org-get-tags now accepts Org element or buffer position as first argument.

This function is intended for us in the definition of a kbd macro in files that are exported to Texinfo.

org-at-heading-p now returns t by default on headings inside folds. Passing optional argument will produce the old behaviour.

Previously, executing PlantUML src blocks always exported to a file. Now, if :results is set to a value which does not include "file", no file will be exported and an ASCII graph will be inserted below the src block.

The new variable name is org-plantuml-args. It now applies to both jar PlantUML file and executable.

Leading < and trailing > in the default values of org-time-stamp-formats and org-time-stamp-custom-formats are stripped.

The Org functions that are using these variables also ignore leading and trailing brackets (<...> and [...], if present).

This change makes the Org code more consistent and also makes the docstring for org-time-stamp-custom-formats accurate.

No changes on the user side are needed if org-time-stamp-custom-formats was customized.

The old function name is similar to other org-time-stamp-format function. The new name emphasizes that org-format-timestamp works on timestamp objects.

New custom argument in org-time-stamp-format makes the function use org-time-stamp-custom-formats instead of org-time-stamp-formats to determine the format.

Optional argument long is renamed to with-time, emphasizing that it refers to time stamp format with time specification.

Optional argument inactive can now have a value no-brackets to return format string with brackets stripped.

Before you could either specify SQL parameters like :dbhost, :dbuser, :database, etc or a :dbconnection parameter which looks up all other parameters from the sql-connection-alist variable. Now it's possible to specify a :dbconnection and additionally other parameters that will add or overwrite the parameters coming from sql-connection-alist.

E.g. if you have a connection in your sql-connection-alist to a server that has many databases, you don't need an entry for every database but instead can just specify :database next to your :dbconnection parameter.

When the result of a regular code block is nil, then that was already treated as an empty list. Now that is also the case for code blocks that post-process the result of another block.

It is now possible to add new styles or modify old ones in biblatex citation processor. See org-cite-biblatex-styles for more information.

When a citation processor is registered, it is now possible to set :cite-styles key to a function, which will be called whenever the list of styles is required.

When CSL style file name is relative, Org first looks into default-directory before trying org-cite-csl-styles-dir.

The function org-lint-add-checker allows one to add personal checks when calling org-lint. See its docstring for more information.

The dvipng option in org-preview-latex-process-alist has a new property transparent-image-converter which is used instead of image-converter when producing transparent images.

Previously :tangle-mode (identity #o755) was the only reasonable way to set the file mode. org-babel-interpret-file-mode has been introduced which will accept three new formats:

• Short octals, e.g. :tangle-mode o755
• ls-style, e.g. :tangle-mode rwxrw-rw-
• chmod-style, e.g. :tangle-mode u+x

Chmod-style permissions are based on the new variable org-babel-tangle-default-file-mode.

org-latex-listings has been renamed to better reflect the current purpose of the variable. The replacement variable org-latex-src-block-backend acts in exactly the same way, however it accepts listings and verbatim in place of t and nil (which still work, but are no longer listed as valid options).

The value of :insert-description is used as the initial input when prompting for a link description. It can be a string (used as-is) or a function (called with the same arguments as org-make-link-description-function to return a string to use).

An example of a such function for info: links is org-info-description-as-command. To access a manual section outside of Org, description may be pasted to shell prompt or evaluated withing Emacs using M-: (wrapped into parenthesis). For example, description of the info:org#Tags link is info "(org) Tags". To restore earlier behavior add to your Emacs init file the following:

(with-eval-after-load 'ol-info
  (org-link-set-parameters "info" :insert-description nil))

org-latex-language-alist unifies into a single list the old language lists for the babel and polyglossia LaTeX packages: org-latex-babel-language-alist and org-latex-polyglossia-language-alist, respectively, which are declared obsolete.

This new list captures the current state of art regarding language support in LaTeX. The new babel syntax for loading languages via ini files and the new command \babelprovide (see: https://mirrors.ctan.org/macros/latex/required/babel/base/babel.pdf) are also supported.

With the new customization option org-texinfo-with-latex set to (its default value) 'detect, if the system runs Texinfo 6.8 (3 July 2021) or newer, Org will export all LaTeX fragments and environments using Texinfo @math and @displaymath commands respectively.

List entries may return nil if they are unable to handle the passed ID. So, responsibility is passed to the next item in the list. Default entries org-attach-id-uuid-folder-format and org-attach-id-ts-folder-format now return nil for too short IDs. Earlier an obscure error has been thrown.

After the change, error text suggests adjusting org-attach-id-to-path-function-list value. The org-attach-dir-from-id function is adapted to ignore nil values and to take first non-nil value instead of the value returned by first org-attach-id-to-path-function-list item.

New policy allows mixing different ID styles while keeping subfolder layout suited best for each one. For example, one can use the following snippet to allow multiple different ID formats in Org files.

(setq org-attach-id-to-path-function-list
      '(;; When ID looks like an UUIDs or Org internal ID, use
        ;; `org-attach-id-uuid-folder-format'.
        (lambda (id)
          (and (or (org-uuidgen-p id)
                   (string-match-p "[0-9a-z]\\{12\\}" id))
               (org-attach-id-uuid-folder-format id)))
        ;; When ID looks like a timestap-based ID. Group by year-month
        ;; folders.
        (lambda (id)
          (and (string-match-p "[0-9]\\{8\\}T[0-9]\\{6\\}\.[0-9]\\{6\\}" id)
               (org-attach-id-ts-folder-format id)))
        ;; Any other ID goes into "important" folder.
        (lambda (id) (format "important/%s/%s" (substring id 0 1) id))
        ;; Fallback to detect existing attachments for old defaults.
        ;; All the above functions, even when return non-nil, would
        ;; point to non-existing folders.
        org-attach-id-uuid-folder-format
        org-attach-id-ts-folder-format))