16.8 Summary of In-Buffer Settings

In-buffer settings start with ‘#+’, followed by a keyword, a colon, 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 only 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 parses and loads the file, and also resets the temporary file cache. Org also parses and loads the document during normal exporting process. Org parses the contents of this document as if it was included in the buffer. It can be another Org file. To visit the file—not a URL—use C-c ' while point is on the line with the 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.

‘overview’	Top-level headlines only.
‘content’	All headlines.
‘showall’	No folding on any entry.
‘show2levels’	Headline levels 1-2.
‘show3levels’	Headline levels 1-3.
‘show4levels’	Headline levels 1-4.
‘show5levels’	Headline levels 1-5.
‘showeverything’	Show even drawer contents.

Dynamic virtual indentation is controlled by the variable org-startup-indented¹⁵⁰.

‘indent’	Start with Org Indent mode turned on.
‘noindent’	Start with Org Indent mode turned off.

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

‘num’	Start with Org num mode turned on.
‘nonum’	Start 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.

‘align’	Align all tables.
‘noalign’	Do 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.

‘inlineimages’	Show inline images.
‘noinlineimages’	Do not show inline images on startup.

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).

‘logdone’	Record a timestamp when an item is marked as done.
‘lognotedone’	Record timestamp and a note when DONE.
‘nologdone’	Do not record when items are marked as done.
‘logrepeat’	Record a time when reinstating a repeating item.
‘lognoterepeat’	Record a note when reinstating a repeating item.
‘nologrepeat’	Do not record when reinstating repeating item.
‘lognoteclock-out’	Record a note when clocking out.
‘nolognoteclock-out’	Do not record a note when clocking out.
‘logreschedule’	Record a timestamp when scheduling time changes.
‘lognotereschedule’	Record a note when scheduling time changes.
‘nologreschedule’	Do not record when a scheduling date changes.
‘logredeadline’	Record a timestamp when deadline changes.
‘lognoteredeadline’	Record a note when deadline changes.
‘nologredeadline’	Do not record when a deadline date changes.
‘logrefile’	Record a timestamp when refiling.
‘lognoterefile’	Record a note when refiling.
‘nologrefile’	Do 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’).

‘hidestars’	Make all but one of the stars starting a headline invisible.
‘showstars’	Show all stars starting a headline.
‘indent’	Virtual indentation according to outline level.
‘noindent’	No virtual indentation according to outline level.
‘odd’	Allow only odd outline levels (1, 3, …).
‘oddeven’	Allow all outline levels.

To turn on custom format overlays over timestamps (variables org-put-time-stamp-overlays and org-time-stamp-overlay-formats), use:

‘customtime’

Overlay custom time format.

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

‘constcgs’	‘constants.el’ should use the c-g-s unit system.
‘constSI’	‘constants.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.

‘fninline’	Define footnotes inline.
‘fnnoinline’	Define footnotes in separate section.
‘fnlocal’	Define footnotes near first reference, but not inline.
‘fnprompt’	Prompt for footnote labels.
‘fnauto’	Create ‘[fn:1]’-like labels automatically (default).
‘fnconfirm’	Offer automatic label for editing or confirmation.
‘fnadjust’	Automatically renumber and sort footnotes.
‘nofnadjust’	Do not renumber and sort automatically.

To hide blocks on startup, use these keywords. The corresponding variable is org-hide-block-startup.

‘hideblocks’	Hide all begin/end blocks on startup.
‘nohideblocks’	Do not hide blocks on startup.

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

‘entitiespretty’	Show entities as UTF-8 characters where possible.
‘entitiesplain’	Leave 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.