Org Syntax

Most elements and objects will be described with the help of syntax patterns, consisting of a series of named tokens written in uppercase and separated by a space, like so:

TOKEN1 TOKEN2

These tokens are often named roughly according to their semantic meaning, For instance, “KEY” and “VALUE” when describing Keywords. Tokens will be specified as either a string, or a series of elements or objects.

Patterns will often also contain static structures that serve to differentiate a particular element or object type from others, but have no semantic meaning. These are simply included in the pattern verbatim. For instance, if a pattern consists of two plus signs (+) immediately followed by a TOKEN it would be written like so:

++TOKEN

Since tokens are written in uppercase, any letters in static structures are distinguished by being written in lowercase.

In a few cases, an instance of an element or object must be preceded or succeeded by a certain pattern, which is not itself part of the element or object. There patterns are specified using the PRE and POST tokens respectively, like so:

PRE TOKEN POST

PRE and POST tokens are only matched against the contents of the containing object. For example, bold object within link description is only matched against the description text *bold* description, not against the full containing link text:

[[https://orgmode.org][*bold* description]]

In this document, unless specified otherwise, case is insignificant.

A Heading is an unindented line structured according to the following pattern:

STARS KEYWORD PRIORITY COMMENT TITLE TAGS

STARS

A string consisting of one or more asterisks (up to org-inlinetask-min-level³ if the org-inlinetask library is loaded) suffixed by a space character. The number of asterisks is used to define the level of the heading. Space character after asterisks is mandatory.

KEYWORD (optional)

A string which is a member of org-todo-keywords-1⁴. Case is significant. This is called a “todo keyword”. ⁵

PRIORITY (optional)

A single alphanumeric character preceded by a hash sign # and enclosed within square brackets (e.g. [#A] or [#1]). This is called a “priority cookie”.

COMMENT (optional)

String “COMMENT”. Case is significant.

TITLE (optional)

A series of objects from the standard set, excluding line break objects. It is matched after KEYWORD and PRIORITY.

TAGS (optional)

A series of colon-separated strings consisting of alpha-numeric characters, underscores, at signs, hash signs, and percent signs (_@#%).

Examples

*
** DONE
*** Some e-mail
**** TODO [#A] COMMENT Title :tag:a2%:

If heading has COMMENT, it will be considered as “commented”.

If the TITLE of a heading is exactly the value of org-footnote-section (Footnotes by default), it will be considered as a “footnote section”. Case is significant.

If ARCHIVE is one of the tags given, the heading will be considered as “archived”. Case is significant.

All content following a heading — up to either the next heading, or the end of the document, forms a section contained by the heading. This is optional, as the next heading may occur immediately in which case no section is formed.

Sections contain one or more non-heading elements. With the exception of the text before the first heading in a document (which is considered a section), sections only occur within headings.

Example

Consider the following document:

An introduction.
* A Heading
Some text.
** Sub-Topic 1
** Sub-Topic 2
*** Additional entry

Its internal structure could be summarized as:

(document
 (section)
 (heading
  (section)
  (heading)
  (heading
   (heading))))

Sections do not include blank lines immediately following the parent heading. It also means that headings containing only blank lines do not contain any section.

* Heading without section, but with blank lines

* Another heading with section

This is a section. It includes everything from "This is" down to "Last
heading", including the trailing blank lines.

* Last heading

Zeroth section follows the same rule.

All elements before the first heading in a document lie in a special section called the zeroth section. It may be preceded by blank lines. Unlike a normal section, the zeroth section can immediately contain a property drawer, optionally preceded by comments. It cannot however, contain planning.

Greater blocks are structured according to the following pattern:

#+begin_NAME PARAMETERS
CONTENTS
#+end_NAME

NAME

A string consisting of any non-whitespace characters, which is not the NAME of a lesser block. Greater blocks are treated differently based on their subtype, which is determined by the NAME as follows:

• center, a “center block”
• quote, a “quote block”
• any other value, a “special block”

PARAMETERS (optional)

A string consisting of any characters other than a newline.

CONTENTS

A collection of zero or more elements, subject to the following condition:

• No line may start with #+end_NAME.

Drawers are structured according to the following pattern:

:NAME:
CONTENTS
:end:

NAME

A string consisting of word-constituent characters, hyphens and underscores (-_).

CONTENTS

A collection of zero or more elements, except another drawer.

Dynamic blocks are structured according to the following pattern:

#+begin: NAME PARAMETERS
CONTENTS
#+end:

NAME

A string consisting of non-whitespace characters.

PARAMETERS (optional)

A string consisting of any characters but a newline.

CONTENTS

A collection of zero or more elements, except another dynamic block.

Footnote definitions must occur at the start of an unindented line, and are structured according to the following pattern:

[fn:LABEL] CONTENTS

LABEL

Either a number or an instance of the pattern WORD, where WORD represents a string consisting of word-constituent characters, hyphens and underscores (-_).

CONTENTS (optional)

A collection of zero or more elements. It ends at the next footnote definition, the next heading, two consecutive blank lines, or the end of buffer.

Examples

[fn:1] A short footnote.

[fn:2] This is a longer footnote.

It even contains a single blank line.

Inlinetasks are syntactically a heading with a level of at least org-inlinetask-min-level³, i.e. starting with at least that many asterisks.

Optionally, inlinetasks can be ended with a second heading with a level of at least org-inlinetask-min-level³, with no optional components (i.e. only STARS and TITLE provided) and the string END as the TITLE. This allows the inlinetask to contain elements.

Examples

*************** TODO some tiny task
This is a paragraph, it lies outside the inlinetask above.
*************** TODO some small task
                 DEADLINE: <2009-03-30 Mon>
                 :PROPERTIES:
                   :SOMETHING: or other
                 :END:
                 And here is some extra text
*************** END

Inlinetasks are only recognized after the org-inlinetask library is loaded.

Items are structured according to the following pattern:

BULLET COUNTER-SET CHECK-BOX TAG CONTENTS

BULLET

One of the two forms below, followed by either a whitespace character or line ending.

• An asterisk (*), hyphen (-), or plus sign (+) character. Note that asterisk * character starting at the beginning of line and followed by whitespace cannot be an item as it would match a heading.
• Either the pattern COUNTER. or COUNTER).

  COUNTER

  Either a number or a single letter (a-z).

COUNTER-SET (optional)

An instance of the pattern [@COUNTER].

CHECK-BOX (optional)

A single whitespace character, an X character, or a hyphen enclosed by square brackets (i.e. [ ], [X], or [-]).

TAG (optional)

An instance of the pattern TAG-TEXT :: where TAG-TEXT is the text up until the last occurrence of the substring " :: " (two colons surrounded by whitespace, without the quotes) on that line. TAG-TEXT is then parsed with the standard set of objects.

CONTENTS (optional)

A collection of zero or more elements, ending at the first instance of one of the following:

• The next item.
• The first line less or equally indented than the starting line, not counting lines within other non-paragraph elements or inlinetask boundaries.
• Two consecutive blank lines.

Examples

- item
3. [@3] set to three
+ [-] tag :: item contents
 * item, note whitespace in front
* not an item, but heading - heading takes precedence

A plain list is a set of consecutive items of the same indentation.

If first item in a plain list has a COUNTER in its BULLET, the plain list will be an “ordered plain-list”. If it contains a TAG, it will be a “descriptive list”. Otherwise, it will be an “unordered list”. List types are mutually exclusive at the same level of indentation, if multiple types are present consecutively then they parse as separate lists.

For example, consider the following excerpt of an Org document:

1. item 1
2. [X] item 2
   - some tag :: item 2.1

Its internal structure is as follows:

(ordered-plain-list
 (item
   (paragraph))
 (item
  (paragraph)
  (descriptive-plain-list
   (item
     (paragraph)))))

Property drawers are a special type of drawer containing properties attached to a heading or inlinetask. They are located right after a heading and its planning information, as shown below:

HEADLINE
PROPERTYDRAWER

HEADLINE
PLANNING
PROPERTYDRAWER

Property drawer can also be present in zeroth section:

BEGINNING-OF-FILE
BLANK-LINES
COMMENT
PROPERTYDRAWER

BLANK-LINES and COMMENT are optional.

Property Drawers are structured according to the following pattern:

:properties:
CONTENTS
:end:

CONTENTS

A collection of zero or more node properties, not separated by blank lines.

Example

* Heading
:PROPERTIES:
:CUSTOM_ID: someid
:END:

Tables are started by a line beginning with either:

• A vertical bar (|), forming an “org” type table.
• The string +- followed by a sequence of plus (+) and minus (-) signs, forming a “table.el” type table.

Tables cannot be immediately preceded by such lines, as the current line would the be part of the earlier table.

Org tables contain table rows, and end at the first line not starting with a vertical bar. An Org table can be followed by a number of #+TBLFM: FORMULAS lines, where FORMULAS represents a string consisting of any characters but a newline.

Table.el tables end at the first line not starting with either a vertical line (|) or a plus sign (+).

Examples

Org table:
| Name  | Phone | Age | Age - 24 |
|-------+-------+-----+----------|
| Peter |  1234 |  24 |       -1 |
| Anna  |  4321 |  25 |        7 |
| Susan |  9876 |  18 |          |
#+TBLFM: @<$4..@>>$4 = $3 - @+1$3

Table.el table:
+------+-----+-----+
|Name  |Phone|Age  |
+------+-----+-----+
|Peter |1234 |24   |
+------+-----+-----+
|Anna  |4321 |25   |
|Turner|     |     |
+------+-----+-----+

Like greater blocks, blocks are structured according to the following pattern:

#+begin_NAME DATA
CONTENTS
#+end_NAME

NAME

A string consisting of any non-whitespace characters. The type of the block is determined based on the value as follows:

• comment, a “comment block”,
• example, an “example block”,
• export, an “export block”,
• src, a “source block”,
• verse, a “verse block”. The NAME must be one of these values. Otherwise, the pattern forms a greater block.

DATA (optional)

A string consisting of any characters but a newline.

• In the case of an export block, this is mandatory and must be a single word.
• In the case of a source block, this is mandatory and must follow the pattern LANGUAGE SWITCHES ARGUMENTS with:

  LANGUAGE

  A string consisting of any non-whitespace characters

  SWITCHES

  Any number of SWITCH patterns, separated by a single space character

  SWITCH

  Either the pattern -l "FORMAT" where FORMAT represents a string consisting of any characters but a double quote (") or newline, or the pattern -S or +S where S represents a single alphabetic character

  ARGUMENTS

  A string consisting of any character but a newline.

CONTENTS (optional)

A string consisting of any characters (including newlines) subject to the same two conditions of greater block’s CONTENTS, i.e.

• No line may start with #+end_NAME.
• Lines beginning with an asterisk must be quoted by a comma (,*) and lines beginning with #+ may be quoted by a comma when necessary (#+).

CONTENTS will contain Org objects and not support comma-quoting when the block is a verse block, it is otherwise not parsed.

Example

#+begin_verse
    There was an old man of the Cape
   Who made himself garments of crepe.
       When asked, “Do they tear?”
      He replied, “Here and there,
 But they’re perfectly splendid for shape!”
#+end_verse

#+begin_src emacs-lisp
"This string
* has "*" escaped.
Otherwise, '* has "*" escaped.' would be treated as a heading (which
is context-free)."

"#+ lines may or may not need to be escaped:
#+end_src if not escaped, would be this source block.
However,
#+keyword: does not interfere with code block end and may be left as is.
#+keyword may be escaped as well, optionally - parser removes all the
commas in ,* and ,#+ lines."
#+end_src

A clock element is structured according to the following pattern:

clock: INACTIVE-TIMESTAMP
clock: INACTIVE-TIMESTAMP-RANGE DURATION
clock: DURATION

INACTIVE-TIMESTAMP

An inactive timestamp object.

INACTIVE-TIMESTAMP-RANGE

An inactive range timestamp object.

DURATION

An instance of the pattern => HH:MM.

HH

A number consisting of any number of digits.

MM

A two digit number.

Examples

clock: [2024-10-12]
CLOCK: [2019-03-25 Mon 10:49]--[2019-03-25 Mon 11:31] =>  0:42
clock: => 12:30

A diary sexp⁷ element is an unindented line structured according to the following pattern:

%%SEXP

SEXP

A string starting with an open parenthesis (, with balanced opening and closing parentheses.

Example

%%(org-calendar-holiday)

A planning element is structured according to the following pattern:

HEADING
PLANNING

HEADING

A heading element.

PLANNING

A line consisting of one or more KEYWORD: TIMESTAMP patterns (termed “info” patterns).

KEYWORD

Either the string DEADLINE, SCHEDULED, or CLOSED.

TIMESTAMP

A timestamp object.

PLANNING must directly follow HEADING without any blank lines in between.

When a keyword is repeated in a planning element, the last instance of it has priority.

Example

*** TODO watch "The Matrix"
    SCHEDULED: <1999-03-31 Wed>
*** TODO take over the world with Org mode
    SCHEDULED: <2006-03-12 Sun> DEADLINE: <2034-03-22 Wed>

A “comment line” starts with a hash character (#) and either a whitespace character or the immediate end of the line.

Comments consist of one or more consecutive comment lines.

Example

# Just a comment
#
# Over multiple lines

A “fixed-width line” starts with a colon character (:) and either a space character or the immediate end of the line.

Fixed-width areas consist of one or more consecutive fixed-width lines.

Example

: This is a
: fixed width area

A horizontal rule is formed by a line consisting of at least five consecutive hyphens (-----).

Keywords are structured according to the following pattern:

#+KEY: VALUE

KEY

A string consisting of any non-whitespace characters, other than call (which would forms a babel call element).

VALUE

A string consisting of any characters but a newline.

When KEY is a member of org-element-parsed-keywords⁶, VALUE can contain the standard set objects, excluding footnote references.

Note that while instances of this pattern are preferentially parsed as affiliated keywords, a keyword with the same KEY as an affiliated keyword may occur so long as it is not immediately preceding a valid element that can be affiliated. For example, an instance of #+caption: hi followed by a blank line will be parsed as a keyword, not an affiliated keyword.

LaTeX environments are structured according to the following pattern:

\begin{NAME}EXTRA
CONTENTS
\end{NAME}

NAME

A non-empty string consisting of alphanumeric or asterisk characters

EXTRA (optional)

A string which does not contain the substring \end{NAME}.

CONTENTS (optional)

A string which does not contain the substring \end{NAME}.

Examples

\begin{align*}
2x - 5y &= 8 \\
3x + 9y &= -12
\end{align*}

Node properties can only exist in property drawers, and are structured according to one of the following patterns:

:NAME: VALUE
:NAME:
:NAME+: VALUE
:NAME+:

NAME

A non-empty string containing any non-whitespace characters which does not end in a plus characters (+).

VALUE (optional)

A string containing any characters but a newline.

Paragraphs are the default element, which means that any unrecognized context is a paragraph.

Empty lines and other elements end paragraphs.

Paragraphs can contain the standard set of objects.

A table row consists of a vertical bar (|) followed by:

• Any number of table cells, forming a “standard” type row.
• A hyphen (-), forming a “rule” type row. Any non-newline characters can follow the hyphen and this will still be a “rule” type row

Table rows can only exist in tables with Org type.

Radio-type links are structured according to the following pattern:

PRE RADIO POST

PRE

A non-alphanumeric character.

RADIO

One or more objects matched by some radio target. It can contain the minimal set of objects.

POST

A non-alphanumeric character.

Example

This is some <<<*important* information>>> which we refer to lots.
Make sure you remember the *important* information.

The first instance of *important* information defines a radio target, which is matched by the second instance of *important* information, forming a radio link.

Plain-type links are structured according to the following pattern:

PRE LINKTYPE:PATHPLAIN POST

PRE

A non word constituent character.

LINKTYPE

A string which is one of the link type strings in org-link-parameters¹¹.

PATHPLAIN

A string containing non-whitespace non-bracket (()[]<>) characters, optionally containing parenthesis-wrapped non-whitespace non-bracket substrings up to a depth of two. The string must end with either a non-punctation non-whitespace character, a forwards slash, or a parenthesis-wrapped substring.¹²

POST

A non word constituent character.

Example

Be sure to look at https://orgmode.org.

Angle-type essentially provide a method to disambiguate plain links from surrounding text, and are structured according to the following pattern:

<LINKTYPE:PATHANGLE>

LINKTYPE

A string which is one of the link type strings in org-link-parameters¹¹

PATHANGLE

A string containing any character but >., where newlines and indentation are ignored.

The angle brackets allow for a more permissive PATH syntax, without accidentally matching surrounding text.

Plain-type links are structured according to one of the following two patterns:

[[PATHREG]]
[[PATHREG][DESCRIPTION]]

PATHREG

An instance of one of the seven following annotated patterns:

FILENAME               ("file" type)
LINKTYPE:PATHINNER     ("LINKTYPE" type)
LINKTYPE://PATHINNER   ("LINKTYPE" type)
id:ID                  ("id" type)
#CUSTOM-ID             ("custom-id" type)
(CODEREF)              ("coderef" type)
FUZZY                  ("fuzzy" type)

Any sequence of spaces, tabs, and newlines inside PATHREG is treated as a single space.¹³

FILENAME

A string representing an absolute or relative file path.

LINKTYPE

A string which is one of the link type strings in org-link-parameters¹¹

PATHINNER

A string consisting of any character besides square brackets.

ID

A string consisting of any character besides square brackets.

CUSTOM-ID

A string consisting of any character besides square brackets.

CODEREF

A string consisting of any character besides square brackets.

FUZZY

A string consisting of any character besides square brackets.

Square brackets and backslashes can be present in PATHREG so long as they are escaped by a backslash (i.e. \], \\).

DESCRIPTION (optional)

One or more objects enclosed by square brackets. It can contain the minimal set of objects as well as export snippets, inline babel calls, inline source blocks, macros, and statistics cookies. It can also contain another link, but only when it is a plain or angle link. It can contain square brackets, but not ]].

Examples

[[https://orgmode.org][The Org project homepage]]
[[file:orgmanual.org]]
[[Regular links]]

Any string that doesn’t match any other object can be considered a plain text object.¹⁴ Within a plain text object, all whitespace is collapsed to a single space. For instance, hello\n there is equivalent to hello there.