org mode: retrieve current heading and parents programmatically

Question

In org-mode whenever I have point on heading it shows me in the mini buffer the full hierarchy. For example, if I have the following in a Org file:

* lvl1
** lvl2
*** lvl3
    some text

And I put point on lvl3 it shows /lvl1/lvl2/lvl3 in the mini buffer. Is there a specific function I can call to obtain this information? I sometimes need to retrieve context and with this it would be easier, no need to move point to the heading.

Answer 1

org-get-outline-path will return a list with the heading hierarchy.

org-format-outline-path will take such a path and format it for display. This is what goes into your mini-buffer.

Answer 2

org-display-outline-path displays (or optionally returns a string of) the hierarchy already formatted.

It also has a few optional parameters to customize its behaviour (defaults included in parenthesis):

• include file name? (no)
• current heading? (no)
• custom separator (defaults to "/")
• just return a string rather than display it? (no).

To obtain a formatted string of the heading including the curret one (lvl3):

(org-display-outline-path nil t "/" t)

=> #( "lvl1/lvl2/lvl3" ...<text properties> )

To strip the text properties from it -- just the string:

(substring-no-properties (org-display-outline-path nil t "/" t))

=> "lvl1/lvl2/lvl3"

---

IMO this method is simpler than using org-get-outline-path, append current heading (lvl3) and joining it with string-join.

The function org-display-outline-path seems to have been available since around version 7.9.

• git log relating to this function
• Documentation for this function (on Worg)