Skip to content
Automatically expand certain Org headings
Shell Emacs Lisp Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


This package automatically expands certain headings in an Org file depending on properties set, making it easy to always get the same initial view when finding a file.



Installing with Quelpa is easy:

  1. Install quelpa-use-package (which can be installed directly from MELPA).
  2. Add this form to your init file:
(use-package org-auto-expand
  :quelpa (org-auto-expand :fetcher github :repo "alphapapa/org-auto-expand"))


Install these required packages:

  • dash

Then put org-auto-expand.el in your load-path, and put this in your init file:

(require 'org-auto-expand)


  1. Define auto-expansion settings in an Org file (see below).
  2. Run org-auto-expand to set visibility accordingly. You may do this automatically in a file with a file- or dir-local variable. See examples.
  • The global minor mode org-auto-expand-mode automatically applies expansion settings when visiting Org files.
  • To start with all entries folded, set the variable org-startup-folded as desired, or use the #+STARTUP keyword.
  • To reset to startup visibility before expanding entries, call org-auto-expand with a prefix argument. This is especially useful when expanding on-demand rather than at file-visit time.

Auto-expansion Settings

Auto-expansion settings may be set in two ways: with Org properties on headings, and with the file- or dir-local variable org-auto-expand-nodes.


Set the auto-expand property on a node to a list of one or more of these values:

  • heading: Show just the heading.
  • body: Show the heading and its body, but not its children.
  • children: Show the heading’s children, but not its body.
  • A number N: Show child headings N levels deep.
  • A symbol that org-show-context accepts as an argument.

For example, in this Org file:

* Daily tasks
:auto-expand: body 1

Things to do every day.

** Check email
** Walk dog

* Weekly tasks

Things to do every week.

** Check tire pressure
** Attempt to walk cat

After running org-auto-expand, you would see:

* Daily tasks

Things to do every day.

** Check email
** Walk dog

* Weekly tasks...

Variable org-auto-expand-nodes

The variable org-auto-expand-nodes may be set as file-local or dir-local (e.g. using command add-file-local-variable). It should be an alist, the key of which should be an Org outline path (a list of heading strings corresponding to a node’s hierarchy), and the value of which should be one of the values accepted by the auto-expand property. The corresponding example, which also calls org-auto-expand automatically:

# Local Variables:
# org-auto-expand-nodes: ((("Daily tasks") body 1))
# eval: (org-auto-expand)
# End:



Initial release.


Bug reports, feature requests, suggestions — oh my!



You can’t perform that action at this time.