17.8 Summary of In-Buffer Settings

In-buffer settings start with ‘#+’, followed by a keyword, a colon, one or more spaces, and then a word for each setting. Org accepts multiple settings on the same line. Org also accepts multiple lines for a keyword. This manual describes these settings throughout. A summary follows here.

C-c C-c activates any changes to the in-buffer settings. Closing and reopening the Org file in Emacs also activates the changes.

#+ARCHIVE: %s_done::

Sets the archive location of the agenda file. The corresponding variable is org-archive-location.

#+CATEGORY

Sets the category of the agenda file, which applies to the entire document.

#+COLUMNS: %25ITEM ...

Set the default format for columns view. This format applies when columns view is invoked in locations where no ‘COLUMNS’ property applies.

#+CONSTANTS: name1=value1 ...

Set file-local values for constants that table formulas can use. This line sets the local variable org-table-formula-constants-local. The global version of this variable is org-table-formula-constants.

#+FILETAGS: :tag1:tag2:tag3:

Set tags that all entries in the file inherit from, including the top-level entries.

#+LINK: linkword replace

Each line specifies one abbreviation for one link. Use multiple ‘LINK’ keywords for more, see Link Abbreviations. The corresponding variable is org-link-abbrev-alist.

#+PRIORITIES: highest lowest default

This line sets the limits and the default for the priorities. All three must be either letters A–Z or numbers 0–9. The highest priority must have a lower ASCII number than the lowest priority.

#+PROPERTY: Property_Name Value

This line sets a default inheritance value for entries in the current buffer, most useful for specifying the allowed values of a property.

#+SETUPFILE: file

The setup file or a URL pointing to such file is for additional in-buffer settings. Org loads this file and parses it for any settings in it when Org opens the main file. If URL is specified, the contents are downloaded and stored in a temporary file cache. C-c C-c on the settings line re-parses and re-loads the file, and also resets the temporary file cache.

Org also parses and loads in-buffer settings from the setup file during normal exporting process. Org parses the in-buffer settings as if it was included in the containing Org buffer. The rest of the contents of setup file is ignored.

To visit the setup file—not a URL—use C-c ' while point is on the line with the setup file name.

#+STARTUP:

Startup options Org uses when first visiting a file.

The first set of options deals with the initial visibility of the outline tree. The corresponding variable for global default settings is org-startup-folded with a default value of showeverything.

overviewTop-level headlines only.
contentAll headlines.
showallNo folding on any entry.
show2levelsHeadline levels 1-2.
show3levelsHeadline levels 1-3.
show4levelsHeadline levels 1-4.
show5levelsHeadline levels 1-5.
showeverythingShow even drawer contents.

Dynamic virtual indentation is controlled by the variable org-startup-indented161.

indentStart with Org Indent mode turned on.
noindentStart with Org Indent mode turned off.

Dynamic virtual numeration of headlines is controlled by the variable org-startup-numerated.

numStart with Org num mode turned on.
nonumStart with Org num mode turned off.

Aligns tables consistently upon visiting a file. The corresponding variable is org-startup-align-all-tables with nil as default value.

alignAlign all tables.
noalignDo not align tables on startup.

Shrink table columns with a width cookie. The corresponding variable is org-startup-shrink-all-tables with nil as default value.

When visiting a file, inline images can be automatically displayed. The corresponding variable is org-startup-with-inline-images, with a default value nil to avoid delays when visiting a file.

inlineimagesShow inline images.
noinlineimagesDo not show inline images on startup.

Bracket links in Org buffers are displayed hiding the link path and brackets. For example, ‘[[https://orgmode.org][Org Website]]’ is, by default, displayed as “Org Website”, hiding the link itself and just displaying its description. Alternatively, the links can be displayed in full. The corresponding variable is org-link-descriptive.

descriptivelinksHide path and brackets in links.
literallinksDo not hide anything.

Logging the closing and reopening of TODO items and clock intervals can be configured using these options (see variables org-log-done, org-log-note-clock-out, and org-log-repeat).

logdoneRecord a timestamp when an item is marked as done.
lognotedoneRecord timestamp and a note when DONE.
nologdoneDo not record when items are marked as done.
logrepeatRecord a time when reinstating a repeating item.
lognoterepeatRecord a note when reinstating a repeating item.
nologrepeatDo not record when reinstating repeating item.
lognoteclock-outRecord a note when clocking out.
nolognoteclock-outDo not record a note when clocking out.
logrescheduleRecord a timestamp when scheduling time changes.
lognoterescheduleRecord a note when scheduling time changes.
nologrescheduleDo not record when a scheduling date changes.
logredeadlineRecord a timestamp when deadline changes.
lognoteredeadlineRecord a note when deadline changes.
nologredeadlineDo not record when a deadline date changes.
logrefileRecord a timestamp when refiling.
lognoterefileRecord a note when refiling.
nologrefileDo not record when refiling.

Here are the options for hiding leading stars in outline headings, and for indenting outlines. The corresponding variables are org-hide-leading-stars and org-odd-levels-only, both with a default setting nil (meaning ‘showstars’ and ‘oddeven’).

hidestarsMake all but one of the stars starting a headline invisible.
showstarsShow all stars starting a headline.
indentVirtual indentation according to outline level.
noindentNo virtual indentation according to outline level.
oddAllow only odd outline levels (1, 3, …).
oddevenAllow all outline levels.

To turn on custom format overlays over timestamps (variables org-display-custom-times and org-timestamp-custom-formats), use:

customtimeOverlay custom time format.

The following options influence the table spreadsheet (variable constants-unit-system).

constcgsconstants.el’ should use the c-g-s unit system.
constSIconstants.el’ should use the SI unit system.

To influence footnote settings, use the following keywords. The corresponding variables are org-footnote-define-inline, org-footnote-auto-label, and org-footnote-auto-adjust.

fninlineDefine footnotes inline.
fnnoinlineDefine footnotes in separate section.
fnlocalDefine footnotes near first reference, but not inline.
fnpromptPrompt for footnote labels.
fnautoCreate ‘[fn:1]’-like labels automatically (default).
fnconfirmOffer automatic label for editing or confirmation.
fnadjustAutomatically renumber and sort footnotes.
nofnadjustDo not renumber and sort automatically.
fnanonCreate anonymous footnotes with org-footnote-new.

To hide blocks or drawers on startup, use these keywords. The corresponding variables are org-hide-block-startup and org-hide-drawer-startup.

hideblocksHide all begin/end blocks on startup.
nohideblocksDo not hide blocks on startup.
hidedrawersHide all begin/end blocks on startup.
nohidedrawersDo not hide blocks on startup.

The display of entities as UTF-8 characters is governed by the variable org-pretty-entities and the keywords

entitiesprettyShow entities as UTF-8 characters where possible.
entitiesplainLeave entities plain.
#+TAGS: TAG1(c1) TAG2(c2)

These lines (several such lines are allowed) specify the valid tags in this file, and (potentially) the corresponding fast tag selection keys. The corresponding variable is org-tag-alist.

#+TODO:’, ‘#+SEQ_TODO:’, ‘#+TYP_TODO:

These lines set the TODO keywords and their interpretation in the current file. The corresponding variable is org-todo-keywords.


Footnotes

(161)

Note that Org Indent mode also sets the wrap-prefix property, such that Visual Line mode (or purely setting word-wrap) wraps long lines, including headlines, correctly indented.