Org syntax in detail

A blank line is a line of spaces and tabs only. Blank lines are not an element: each one belongs to an element before it, counted in that element's :post-blank (or :pre-blank). The rule is the narrowest element that ends there, with these exceptions:

* Heading

Text.

- a

- b


After the list.

Here the headline has a :pre-blank of 1, the paragraph Text. a :post-blank of 1, the first item a :post-blank of 1 (its paragraph 0), and the list a :post-blank of 2. Two blank lines end a list, and also a footnote definition, so they are part of those elements' syntax.

For an item or a footnote definition, :pre-blank is 0 when the contents start on the first line; otherwise it counts the lines from the first line to the contents, the first line included. For a headline it counts only the blank lines.

Indentation is the spaces and tabs at the start of a line. Headlines, inlinetasks, footnote definitions and diary sexps must start at column 0; every other element may be indented. Indentation has a meaning only in plain lists, where it is measured with spaces as one column and tabs as eight.

The tree keeps indentation as text. It is removed when the contents are used, as Emacs removes it:

• Exporting a paragraph or a verse block removes the smallest indentation of its lines (org-element-normalize-contents). For the first paragraph of an item or a footnote definition that starts on the first line, the first line is left out when that smallest indentation is computed.
• The code of a source or example block loses its common indentation (org-remove-indentation) unless the block has the -i switch or org-src-preserve-indentation is set (it is not, by default). Lines keep the indentation beyond the common part.
• Export blocks, LaTeX environments and table.el tables lose their common indentation when exported.

With the default settings, a. text is a paragraph, not an item. Kalem uses the default, and no setting of Kalem turns alphabetical bullets on.

[@N] after the bullet sets the item's number, :counter. The forms [@start:N] and [@c] (a letter, counted from A = 1) are read too, whatever the alphabetical setting; - [@c] x has counter 3. A counter may follow any bullet, also -.

[ ] is off, [X] on and [-] partial (:checkbox off, on, trans). The X must be upper case: [x] is still taken as the checkbox part of the line, so it is not in the item's text, but the item has no checkbox.

In an item whose bullet is -, + or *, the text before the last :: of the first line (with a blank before it, and a blank or the end of line after it) is the item's tag, parsed for objects without line breaks. In an ordered item, :: is ordinary text.

A plain list is a run of items at the same indentation; a sub-list is a list inside an item. The list's :type is decided by its first item only: ordered when the first bullet is a number (or letter), descriptive when the first item has a tag, else unordered. Items of different bullet kinds may share one list.

An item ends at the next item of the same or smaller indentation, and at the first non-blank line indented no more than the item's bullet. Lines inside blocks (any #+BEGIN_ or #+BEGIN: line up to its end line) and drawers do not count for this. Inlinetasks inside a list are skipped. A list ends:

• at two consecutive blank lines;
• at a line indented no more than its first item that is not an item;
• at a headline, or the end of the element that holds it.

- first
  continued inside the item

  - sub-item
- second
Not in the list: back at the list's indentation.

#+begin_NAME PARAMETERS … #+end_NAME, with any non-blank NAME that is not comment, example, export, src or verse. center makes a center block, quote a quote block, any other name a special block with :type NAME (as written) and :parameters the rest of the line, trimmed. Names are case-insensitive. The contents are elements. Without its end line the block is paragraph text.

:NAME: alone on a line, where NAME is letters, digits, - and _, up to the first :END: line (case-insensitive). A drawer cannot hold another drawer, since the first :END: closes it. Without an :END: line, the opening line is paragraph text.

A drawer named PROPERTIES is a property drawer only right after a headline or inlinetask, or after its planning line, or at the start of the document (after blank lines and comment lines). Anywhere else it is an ordinary drawer named PROPERTIES, and its lines are paragraph text. Each line of a property drawer is a node property:

:NAME: VALUE
:NAME+: VALUE

NAME is any non-blank text; :NAME+: appends to the value. The headline gets each property as :NAME in upper case.

#+BEGIN: NAME PARAMETERS
...
#+END:

NAME is letters and digits only, and the parameters must be separated from it by a blank: in #+BEGIN: a-b c the name is a and there are no parameters. The end line is #+END: or #+END. Kalem shows dynamic blocks and never updates them.

#+begin_src LANGUAGE SWITCHES HEADER-ARGUMENTS
#+begin_example SWITCHES

In a source block the switches come right after the language and are any sequence of -l "FORMAT", -i, -k, -r, -n N, +n N (the number optional); the rest of the line is the header arguments (:parameters). An example block takes the whole rest of its line as switches.

References give the label itself only when the labels stay in the code and -k is absent. So -r alone removes the labels and references give line numbers; -n -r -k keeps the labels and references still give line numbers.

The number may be written with or without a space (-n 5 or -n5). Kalem's exporters currently recognize only the form with a space and ignore -n5; Emacs numbers from 5. This is a bug.

In source, example and export blocks, a line whose first non-blank characters are commas followed by * or #+ loses one comma in the block's value: ,* x gives * x, ,,* x gives ,* x, ,#+x gives #+x. This protects lines that would otherwise be headlines or end the block. Comment blocks and verse blocks are not unquoted: their commas stay.

#+begin_src org
,* A headline inside the code
#+end_src

PRE MARKER CONTENTS MARKER POST

So x*b*y is plain text and (*b*) is bold. Code and verbatim contents are not parsed; the other four contain objects. Where _ could open an underline or a subscript, as in (_u_), the underline wins.

NAME is a name of org-entities: letters only, or one of the names with digits, there4, sup1 to sup3, frac12, frac14 and frac34. \alpha1 is the entity alpha followed by 1; \alphax is not an entity, and is read as a LaTeX fragment.

A single-dollar fragment needs: no $ just before the opening one; a first character that is not a blank, ,, . or ;; a last character (before the closing $) that is not a blank, , or .; and after the closing $ punctuation, a blank, a bracket, a quote or the end of the line. So $x$ and $?$ are fragments, $x$y, $ x$ and $x $ are not. \foo[a]{b}{c} is one fragment.

@@BACKEND:VALUE@@. BACKEND is letters, digits and -; VALUE runs to the next @@ and may be empty. @@my_backend:x@@ is not a snippet (_ is not allowed).

\\ at the end of a line, blanks after it allowed, and not preceded by another backslash. It is a line break also when it is alone on its line.

{{{NAME}}} or {{{NAME(ARGS)}}}. NAME starts with a letter and goes on with letters, digits, - and _; it is case-insensitive (:key is lower case). Arguments are separated by commas; \, is a literal comma. Runs of blanks and newlines inside the arguments become one space, and blanks after a comma are kept: {{{m(a, b\, c)}}} has the arguments a and b, c with a leading space. The arguments may span lines of a paragraph.

<<TARGET>>: the text is anything but <, > and newlines, and does not start or end with a blank. <<<RADIO>>> has the same rule and may contain the minimal objects (emphasis, entities, LaTeX fragments, sub- and superscripts). Every occurrence of a radio target's text elsewhere becomes a link to it, when the characters around it are not letters or digits (or are characters after which a line may break, as in Chinese text). Blanks in the target match any run of whitespace.

[N/M] or [N%], the numbers optional: [/], [%], [1/] are cookies too. The commands fill them in.

_ or ^ right after a non-blank character, followed by one of:

• *, as in a^*;
• braces {...} or parentheses (...), nesting three levels deep at most, contents parsed for objects (:use-brackets-p is t for braces);
• an optional sign, then letters, digits, ,, \ and ., ending with a letter or digit: x^-2, A_i,j, x_1.5.

a^+ is not a superscript. The export options ^:{} and ^:nil change how they export, not the tree.

[cite/STYLE/VARIANT:GLOBAL-PREFIX; REFERENCES; GLOBAL-SUFFIX]

:style is the whole text after cite/, t/f for [cite/t/f:...]: letters, digits, -, _ and /. A reference is PREFIX @KEY SUFFIX, the references separated by ;. A key is word characters and any of -.:?!`'/*@+|(){}<>&_^$#%~. The global prefix is the text before the ; that precedes the first key, and the global suffix the text after the last ; when no key follows it. Blanks after the colon and before the closing bracket do not matter. Prefixes and suffixes may contain objects, but not line breaks, citations, footnote references or links.

So https://orgmode.org. links to https://orgmode.org, without the period, and https://x.org/a_(b) keeps its parentheses. A word such as foo:bar is not a link unless foo is a registered type.

A bracket link's PATH is, in this order: a file when it is absolute or starts with ./ or ../; TYPE:PATH when TYPE is registered; (REF), a code reference; #ID, a custom ID; anything else a fuzzy link. For file links, file+APP: sets :application, and ::SEARCH after the path sets :search-option. Abbreviations from #+LINK are expanded before this. The description may contain the minimal objects, export snippets, inline calls, inline source blocks, macros and statistics cookies, but no other link.

call_NAME(ARGS), with optional [HEADER] before and after the arguments, and src_LANG{CODE} or src_LANG[HEADERS]{CODE}. Both must start a word (xcall_f(1) is not a call) and are case-sensitive. The parentheses of a call are required; brackets, parentheses and braces must balance inside their parts.

org-table-align aligns a column by the first field that is an alignment cookie (<l>, <c>, <r>, with an optional width); without one, the column is aligned right when at least half of its non-empty fields (org-table-number-fraction, 0.5) look like numbers, and left otherwise. Every row counts, the header too. A field looks like a number when it matches org-table-number-regexp:

• digits with signs, dots, ^, e, d, x, parentheses, % and : around them, optionally after < or > (12, -3.5, 2.4e-08, 2x10^12, 4.034+-0.02, 12:30, 50%);
• a hexadecimal number 0x1F, or a number in a base, 16#FF;
• nan, inf, -inf, uinf.

A column with no non-empty field is aligned right.

A table may be followed by several #+TBLFM: lines; the parser keeps them all (:tblfm). The first is in force: recalculating the table applies it. Recalculating with the cursor on a later line applies that line's formulas once, leaving the first line as it is, as C-c C-c there does in Emacs (org-table-calc-current-TBLFM): a way to keep alternative formulas.

| x | y |
|---+---|
| 1 |   |
#+TBLFM: $2=$1*2
#+TBLFM: $2=$1*3