I start this post by introducing what the Org mode global cycling command does, what kind of subtree folding I actually need, and then share the solution with code snippets.

Org Global Cycle #

Org mode has a built-in org-global-cycle command that you might be familiar with. It’s bound by default to the S-TAB key. Each time this command is called, the Org buffer will cycle through these states:

1. Overview: Show only the Level 1 headings and collapse everything underneath.
2. Contents: Show only the Org headings and collapse all the content.
3. Show All: Expand all the headings and show their contents too.

If a numeric prefix N is used with this command, it will show only the Org headings up to Level N. For example, C-2 S-TAB will show only the headings up to Level 2.

This is a really helpful command, but I needed something different ..

Skeleton of only Post headings #

I maintain most of this website’s content in a single Org file. I have dozens of blog posts organized in Org subtrees, which I further organize under “category” headings .. It kind of looks like the below mock-up: It’s amazing how many features PlantUML has. If you are interested in creating diagrams like these, check out the PlantUML Salt syntax.

As we can see,

• All the post subtrees are not at Level 1 headings.
• They are also not at a fixed Level N.
• The heading level of the post depends on how many parent categories that post has (and that will also change over time).

I needed to basically show everything leading up to a post subtree heading, and then collapse all the content under that post; even the sub-headings.

The “Collapse All Posts” function #

The modi/org-hugo-collapse-all-posts function defined below meets the above requirement:

1. It first widens the whole buffer and expands all the headings.
2. Then it loops through all the headings and collapses all the post subtrees i.e. all the subtrees that have the EXPORT_FILE_NAME property set. This is where I use the org-map-entries magic.
3. Finally it looks for Org headings that begin with “Footnotes” or “COMMENT” and collapses them as well.

I am using the development version of Org mode (version 9.6, yet to be released as of <2022-06-15 Wed>) which has the new org-fold library. This library obsoletes the use of outline.el library and other code-folding related functions in Org mode. So cl-flet is used to create function symbol aliases that use the org-fold-* functions if available, otherwise they fall back to the legacy functions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

(defun modi/org-hugo-collapse-all-posts ()
  "Collapse all post subtrees in the current buffer.
Also collapse the Footnotes subtree and COMMENT subtrees if
present.

A post subtree is one that has the EXPORT_FILE_NAME property
set."
  (interactive)
  (cl-flet ((show-all (if (fboundp 'org-fold-show-all)
                          #'org-fold-show-all
                        #'org-show-all))
            (hide-subtree (if (fboundp 'org-fold-hide-subtree)
                              #'org-fold-hide-subtree
                            #'outline-hide-subtree)))
    (widen)
    (show-all '(headings))
    ;; Collapse all the post subtrees (ones with EXPORT_FILE_NAME
    ;; property set).
    (org-map-entries #'hide-subtree "EXPORT_FILE_NAME<>\"\"" 'file)
    ;; Also hide Footnotes and comments.
    (save-excursion
      (goto-char (point-min))
      (while (re-search-forward "^\\(\\* Footnotes\\|\\*+ COMMENT\\)"
                                nil :noerror)
        (hide-subtree)))))

Binding with C-u C-c TAB #

The function is ready, but let’s now add a bit of convenience to it.

If a point is under a subtree, C-c TAB will collapse that subtree while showing only Level 1 headings, and if a numeric prefix is used, it will show only those many levels of headings. I decided to bind the above function to C-u C-c TAB because,

1. The behavior of modi/org-hugo-collapse-all-posts falls in the same category as that of C-c TAB.
2. The C-u C-c .. binding rolls off the fingers pretty nicely 😃.

This binding is achieved using one of my favorite Emacs features .. the advice system. The :before-until Advice Combinator is used here, which means that if the advising function (below) returns a nil, the advised or the original function org-ctrl-c-tab is not called.

The advising function below detects if the C-u prefix argument is used. If it is, the modi/org-hugo-collapse-all-posts function is called, otherwise the original org-ctrl-c-tab function is called.

1
2
3
4
5
6
7
8
9

(defun modi/org-ctrl-c-tab-advice (&rest args)
  "Run `modi/org-hugo-collapse-all-posts' when
doing \\[universal-argument] \\[org-ctrl-c-tab]."
  (let ((do-not-run-orig-fn (equal '(4) current-prefix-arg)))
    (when do-not-run-orig-fn
      (modi/org-hugo-collapse-all-posts))
    do-not-run-orig-fn))

(advice-add 'org-ctrl-c-tab :before-until #'modi/org-ctrl-c-tab-advice)

Result #

After evaluating the above two snippets, when I do C-u C-c TAB in my “blog posts” Org buffer, I see this:

It matches that earlier mockup — Mission accomplished! 💯

Below question on Mastodon by the user @postroutine inspired me to write this post:

I got a lot of Org-Mode headings and I want to modify their properties (add, remove, edit). Is there a function to do the same modifications on each heading?

I think that the best solution to that question is using the org-map-entries function.

But somehow when replying to that question then, that wasn’t what first came to my mind! .. when ironically that function is the main function that enables my preferred subtree-based flow in ox-hugo 😆. So I am writing this post to better ingrain the following concept in myself ..

Next,

1. I will give a give introduction to the org-map-entries API.
2. Then provide a super-short solution to the above question.

org-map-entries API #

I will give only a broad level overview on how to use this function. I would encourage the reader to refer to the resources at the end of this post to learn more about it.

So let’s start by looking at this function’s signature:

(org-map-entries FUNC &optional MATCH SCOPE &rest SKIP)

The org-map-entries function iterates through all the headings meeting the MATCH criteria in the determined SCOPE, and then calls the specified function FUNC at each of those headings.

• The FUNC function accepts no arguments and is called at the beginning of each Org heading.
• The optional second argument MATCH is either nil, t or a search string.
  • If MATCH is nil or t, all headings will be visited by the iteration and FUNC will be called on all of them.
  • But if MATCH is a string, the headings will first be filtered based on that string and then the FUNC will be called on only those.
• For explanations on the optional SCOPE and SKIP arguments, see Org Info: Using the Mapping API or C-h f org-map-entries from within Emacs.

Here’s a typical org-map-entries call that loops through all the headings in the visible buffer: (org-map-entries #'some-function) where all the optional argument values are nil. Next, we’ll see some examples of string-type MATCH arguments used for filtering the headings.

MATCH strings #

Below table shows few examples of match string patterns.

Comparison Types #

• If the comparison value is a plain number, a numerical comparison is done, and the allowed operators are ‘<’, ‘=​’, ‘>’, ‘<=​’, ‘>=​’, and ‘<>’.
• If the comparison value is enclosed in double quotes, a string comparison is done, and the same operators are allowed.
• If the comparison value is enclosed in curly braces, a regexp match is performed. For this comparison, only ‘=​’ (regexp matches) and ‘<>’ (regexp does not match) operators are allowed.
• Comparison with dates and Group Tags is also possible. See Org Info: Matching tags and properties for more details.

Other notes #

• The property names are case-insensitive. So these all work the same: "COLOR<>\"blue\"", "color<>\"blue\"", "Color<>\"blue\"".
• The “tag” and “property” matches can be mixed up using the boolean ‘&’, ‘|’, ‘+’ and ‘-​’ operators. So searching ‘+LEVEL=3+boss-TODO​="DONE"’ lists all level three headlines that have the tag ‘boss’ and are not marked with the TODO keyword ‘DONE’.
• ‘&’ binds more strongly than ‘|’.
• Grouping of match expressions using parentheses is not supported.

Example: Modifying a property in all headings #

Below is an example solution to the Mastoson question that I referenced in the beginning of this post.

(defun test/set-property-at-heading ()
  "Function to be called at the beginning of an Org heading."
  (let ((el (org-element-at-point)))
    (org-set-property "foo" (org-element-property :title el))))
(org-map-entries #'test/set-property-at-heading)

• It defines a function that parses the Org element at point using org-element-at-point, gets the title property of the element This function is designed to be called by org-map-entries and so the point at the time of calling this function will always be on a heading. , and sets that to the headline element’s foo property.
• The org-map-entries call now simply calls this function on each heading in the visible scope of the Org buffer.

org-map-entries References #

• C-h f org-map-entries
• Org Info: Using the Mapping API
• Org Info: Matching tags and properties