Org

There is no separate formal grammar of Org. The Org Syntax document on Worg describes the syntax in prose, and org-element.el implements it; where the two disagree, the implementation decides. Kalem follows:

Defaults are those of emacs -Q with Org 9.7 and org-inlinetask loaded: variables that change parsing or behavior (org-todo-keywords, org-use-tag-inheritance, org-footnote-section and the rest) start at their Emacs defaults, and Kalem's settings change only the ones the settings chapter names.

The oracle is Emacs 30.1 itself. Each layer of the Org mode is compared with it by a differential test:

kalem diff-emacs runs emacs -Q --batch -l tests/emacs/dump.el on the files (or reads dumps made earlier, with --emacs-dumps DIR), dumps Kalem's tree in the same JSON (kalem dump --format emacs-json), and compares the two node by node. The affiliated keyword properties :caption, :header, :plot and :results are not compared; :name is. A node that Emacs lets run past the end of its parent is counted as a known difference rather than a failure (see below).

kalem diff-emacs --summary tests/corpus/org-mode/org-manual.org
kalem diff-emacs --model --summary tests/corpus/model/*.org

The committed corpus is tests/corpus; tests/corpus/LICENSES.md records the source and license of every file.

tests/corpus/fetch-extended.sh clones the whole Org repository at release_9.7.11 and Worg at 22fc0631 into .cache/; CI runs the parser and model differentials on it too. The export cases are in tests/export/cases, and the Worg files exported by Emacs make the extended export corpus.

A file named *.org (or *.org_archive) is strict Org. RFC 0001 (section 3.7, decision D24) once let Kalem add word-processor formatting to Org files through Org's extension points: spans between @@kalem:…@@ snippets, #+ATTR_KALEM: lines for alignment and spacing, and a #+KALEM: keyword for the document's defaults. The owner had this mechanism removed (T2.13.13): Kalem no longer writes these additions, and what a format cannot express is not offered in it.

A file that still has them keeps them byte for byte. Kalem shows them as Emacs does, as an export snippet for another back-end, an unknown affiliated keyword and an unknown keyword, and its exports drop them exactly as Emacs's do. kalem check lists each one as kalem-markup-in-org.

• Lossless. parse(text).syntax().to_string() == text for every input.
• Error tolerant. There is no invalid input and no panic. Malformed constructs parse as Emacs parses them, usually as paragraph text.
• Incremental. An edit reparses only the elements it can affect, and the result is identical to a full parse (property tests and fuzzing check this). Three levels are tried in order: the elements of one section around the edit; the whole section, when the edited lines contain an end line (#+END..., :END:, \end{...}) or a footnote definition; the whole document, when the edit changes the headline structure, an in-buffer setting that the parser reads, or a radio target. Documents with CRLF line endings or a byte order mark keep a second tree of the normalized text and reparse incrementally there.
• Line endings. A file with \r\n line endings is parsed as Emacs parses it after decoding: carriage returns are in the tree but in no value.
• Character classes. Word, blank and case tables are generated from Emacs (tools/gen-tables.el), so emphasis boundaries and case folding agree with Org for every Unicode character.

The SyntaxKind enum has token kinds, node kinds shared with org-element and a few structural node kinds.

Tokens:

Structural nodes without an org-element counterpart, which give shape to syntax Emacs keeps in properties:

The shared kinds are listed in the next three sections. The document node is DOCUMENT (org-data).

A headline is a line starting with one or more stars and a space. Its parts, in order, are all optional but the stars:

#+TODO: TODO NEXT(n) WAIT(w@/!) | DONE(d) CANCELLED(c@)
* NEXT [#A] COMMENT Write the chapter on tables :writing:book:

• the stars, whose count is the true level; with #+STARTUP: odd the level is computed as Org computes it for odd levels only;
• a TODO keyword, one of the document's keywords (default TODO and DONE);
• a priority cookie [#X] with any single character;
• COMMENT, which makes the headline commented (:commentedp);
• the title, parsed for objects (no line breaks);
• tags, :a:b: at the end of the line; the tag ARCHIVE makes the headline archived (:archivedp).

A headline whose title is the footnote section name (Footnotes) is the footnote section. A section is the text between a headline and the next headline; the text before the first headline is the zeroth section. A section contains no headlines; a headline contains its section and its child headlines, as in org-element.

The typed wrapper ast::Headline gives :level, :todo-keyword, :todo-type, :priority, :commentedp, :tags, :archivedp, :raw-value, :pre-blank, the planning line and the property drawer.

A planning line directly follows a headline and holds SCHEDULED:, DEADLINE: and CLOSED: timestamps in any order:

* TODO Submit the paper
DEADLINE: <2026-10-15 Thu -3d> SCHEDULED: <2026-10-05 Mon 09:00 +1w>

When a keyword is repeated and the timestamps overlap, Kalem keeps the timestamp Emacs uses and drops an overlapping one (a listed difference).

A property drawer follows the headline, or its planning line, or starts the zeroth section (the document's own properties). Each line is a node property :KEY: value; :KEY+: value appends to a value.

* Chapter
:PROPERTIES:
:CUSTOM_ID: tables
:EFFORT:   2:00
:END:

A drawer is :NAME: on a line of its own, contents, and :END:. A drawer line without :END: is paragraph text. LOGBOOK is the drawer state changes and clocks go into when logging into a drawer is on.

With org-inlinetask loaded (the default here), a headline of at least org-inlinetask-min-level stars (15; 29 with #+STARTUP: odd) is an inlinetask: a task inside a section, closed by the next line of at least org-inlinetask-min-level stars followed by END, or standing alone on one line. It does not end the section it is in.

An affiliated keyword attaches to the element right after it: #+CAPTION: (with an optional short caption in brackets, and its value parsed for objects), #+NAME:, #+HEADER:, #+PLOT:, #+RESULTS: (with an optional hash in brackets) and #+ATTR_BACKEND: for any back-end name. The old names DATA, LABEL, RESNAME, SOURCE, SRCNAME and TBLNAME are read as NAME, RESULT as RESULTS, HEADERS as HEADER, as org-element-keyword-translation-alist has them. Affiliated keywords followed by a blank line or by the end of their container attach to nothing and are plain keywords; kalem check reports them as orphaned-affiliated-keyword.

Every element takes affiliated keywords except headlines, inlinetasks, sections, planning lines, property drawers, node properties, items, table rows, clocks and comments; keywords before those are plain keywords. CAPTION and HEADER may repeat and accumulate, as do the ATTR_ keywords; for the others the last one counts. CAPTION and RESULTS take a second value in brackets. Only CAPTION's value is parsed for objects in the tree (org-element-parsed-keywords); the exporter parses TITLE, AUTHOR, DATE and its back-end's parsed keywords when it reads them.

#+CAPTION[Short]: Results of the second run.
#+NAME: tab:results
#+ATTR_LATEX: :booktabs t
| Run | Time |
|-----+------|
|   2 | 4.1  |

Which objects a container may hold is org-element-object-restrictions:

A bracket link [[target]] or [[target][description]] resolves as org-element-link-parser resolves it: a target starting with /, ./ or ~ is a file; #id is a custom ID; (ref) a code reference; type:path a link of that type when the type is registered; anything else is a fuzzy link to a target, a name or a headline. Plain links (https://orgmode.org) and angle links (<https://orgmode.org>) need a registered type. Text matching a radio target is a radio link.

The registered types are fixed, since Emacs's set depends on the libraries loaded in a session: those of emacs -Q with Org 9.7 plus attachment (DEFAULT_LINK_TYPES):

attachment bbdb bibtex doi docview elisp eww file file+emacs file+sys
ftp gnus help http https id info irc mailto mhe news rmail shell w3m

#+LINK: key replacement defines an abbreviation: key:tag becomes the replacement with %s replaced by the tag, or %h by the tag URL-encoded, or the tag appended. A replacement with %(function) is Lisp and is not expanded.

Internal links resolve as org-link-search resolves them: to a <<target>>, a #+NAME, a headline title, a CUSTOM_ID, a code reference, or a radio target; id: links to an entry of the same document with that ID property.

The 414 entities of org-entities.el (Org 9.7.11) are recognized, each with its LaTeX, HTML, ASCII, Latin-1 and UTF-8 renderings. A name given twice in org-entities (deg, sup) takes the first.

A log entry that takes a note (lognotedone, a keyword's @, and the lognote… values) asks for it after the command, as Emacs opens its note buffer; cancelled, nothing is logged. Add Note (org-add-note) writes "Note taken on" with a note into the entry's log.

Other values (hidestars, inlineimages, latexpreview, entitiespretty, hideblocks, align, and the rest) are ignored: they change neither the file nor what it means.

Keyword sets are org-todo-sets: one per #+TODO, #+SEQ_TODO or #+TYP_TODO line, in Emacs's order. A keyword may carry a fast key and logging settings, WAIT(w@/!): @ asks for a note, ! records a time, the part before / applies on entering the state and the part after on leaving it. The LOGGING property overrides these and #+STARTUP.

Tags come from the headline, from its ancestors (org-use-tag-inheritance, default all) and from #+FILETAGS, less org-tags-exclude-from-inheritance. Group tags from #+TAGS expand in match strings, as org-tags-expand does.

org-entry-get semantics: drawer properties of the entry; with inheritance, the ancestors', the document's (its top property drawer and #+PROPERTY) and the global ones. org-use-property-inheritance is nil by default. KEY+ values append with a space. The special properties are computed:

ALLTAGS BLOCKED CATEGORY CLOCKSUM CLOCKSUM_T CLOSED DEADLINE FILE ITEM
PRIORITY SCHEDULED TAGS TIMESTAMP TIMESTAMP_IA TODO

Allowed values come from KEY_ALL properties and the fixed global ones. As in Emacs, org-entry-get returns the last value of a key given twice in one drawer and org-entry-properties the first.

An entry's category is its CATEGORY property (inherited), else the last #+CATEGORY of the document, else org-category, else the file name without its extension.

kalem query FILE... MATCH and the model accept org-make-tags-matcher syntax: tags with +, -, & and |, regular expressions in braces, property comparisons (PRIORITY="A", LEVEL>1, SCHEDULED<"<today>"), and a TODO part after / (/! for not-done states only). Emacs's quirks that change results are kept (listed in the known differences).

• Statistics cookies ([2/5], [40%]) are computed as (org-update-statistics-cookies 'all) does: from checkboxes, then from the TODO states of child headlines, which win; hierarchical by default.
• A footnote reference finds its definition as org-footnote-get-definition does.
• Clock sums follow org-clock-sum: closed CLOCK: lines, per heading including its subtree, measured in the system time zone.

An Org table is a run of lines starting with |. A line of dashes and + after the bar is a rule. Alignment is org-table-align's: numbers right, other fields left, the <l>, <c>, <r> and <N> cookies honored, widths measured as Emacs measures display width, with the hidden parts of bracket links left out. A tab in a field counts as one column (a listed difference).

Import Table (table.import, file) is org-table-import: the file, decoded as the editors decode files (a byte order mark, a legacy encoding), is inserted at the cursor on a line of its own and made a table as org-table-convert-region does with its separator guessed: tabs when every non-empty line has one, else commas when every one has one (quoted fields with doubled quotes), else runs of blanks. One addition: a file that opens as CSV and that this reader would misread, because its delimiter is neither a comma nor a tab (;, |) or a quoted field holds a line break, is read as CSV mode reads it (see the CSV chapter) and converted as Convert to Org Table converts it: a rule under a detected header, line breaks in values as spaces. Export Table (table.export, file) is org-table-export: CSV for a .csv name, TSV otherwise.

The table engine (crate org-table) evaluates formulas as Emacs does: it substitutes the referenced fields into the formula's text, as org-table-eval-formula does, and evaluates the result with a reimplementation of the part of Calc that table formulas use, in Org's Calc modes (12 digits of working precision, results shown with 8 significant digits, degrees).

#+CONSTANTS: vat=0.2
| Item  | Qty | Price |   Net | Gross |
|-------+-----+-------+-------+-------|
| Paper |   3 |  4.50 | 13.50 | 16.20 |
| Ink   |   2 | 12.00 | 24.00 | 28.80 |
|-------+-----+-------+-------+-------|
| Total |     |       | 37.50 | 45.00 |
#+TBLFM: $4=$2*$3;%.2f::$5=$4*(1+$vat);%.2f::@>$4=vsum(@I..@II);%.2f::@>$5=vsum(@I..@II);%.2f

Left-hand sides: a column ($3, $>, $name), a field (@2$3, @>$<), a range of fields (@2$1..@4$3), and the column names of a ! row. Formulas are applied in Emacs's order: column formulas row after row, then field formulas, each in the order of their left-hand sides, each seeing what the ones before it wrote; a dependency graph would give other results. Iterating (C-u C-u C-c *, kalem table recalc --iterate) repeats at most ten times; a table that does not settle is left as the tenth pass wrote it, with the error "No convergence after 10 iterations", as in Emacs.

References on the right-hand side:

Calc as reproduced:

• Numbers: integers of any size, fractions, decimal floats with Calc's rounding, to the digit; infinities (inf, uinf) and nan; dates and times (a timestamp in a field is a date; the difference of two is days) and durations.
• Operators: +, -, *, /, ^, % (percent or remainder), \ (integer division), mod (a modulo form: 10 mod 3 is 1 mod 3, and arithmetic on it stays modulo 3; the function mod(10, 3) is the remainder, 1), ! and !! (factorials), the comparisons <, >, <=, >=, =, ==, !=, and &&, ||, !, ?:; implicit multiplication binds tighter than /, as in Calc.
• Functions: abs, sign, floor, ceil, round, trunc, sqrt, exp, ln, log, log10, sin, cos, tan, arcsin, arccos, arctan, sinh, cosh, tanh, arcsinh, arccosh, arctanh, sec, csc, cot, rad, deg, sqr, inv, hypot, nroot, round with a number of places, fact, choose, perm, gcd, lcm, idiv, fdiv, min, max, if, year, month, day, weekday; number theory: prime, nextprime, prevprime, totient, isqrt, ilog; the parts of a float mant and xpon; frac (a float as a fraction, within a tolerance); the bitwise functions on 32-bit words (a last argument gives another size, 0 for unbounded integers, a negative one for signed words) and, or, xor, diff, not, lsh, rsh, ash, rash, rot, clip; random (an integer below n, a float times a real, a point of an interval, an element of a vector); the vector functions vsum, vprod, vmax, vmin, vcount, vlen, vmean, vmedian, vvar, vsdev, vpvar, vpsdev, and those that build and take apart vectors: vec, cvec, index, rev, sort, rsort, grade, rgrade, head, tail, rhead, rtail, cons, rcons, vconcat, subvec, find, vmask, mrow, mcol, trn, arrange, histogram, string, and the sets rdup, vunion, vint, vdiff, vxor, vcompl, vspan, vfloor, vcard, whose members may be intervals (vunion([1..3], [2..6]) is [1 .. 6]).
• Complex numbers, written (2, 3): arithmetic and integer powers, and what sqrt, ln, log10, ^, arcsin and arccos give outside the reals (sqrt(-4) is (0, 2), ln(-1) is (0., 3.1415927)), with abs, arg, re, im and conj.
• Modulo forms of formulas: x mod 3 is (1 mod 3) x, and sums and products of them keep their coefficients modulo 3.
• Formulas over text fields stay symbolic, with Calc's basic simplifications (x + 2, 2 a).

Flags after the last ; are read as org-table-eval-formula reads them:

| Task |     Time |
|------+----------|
| A    |     1:30 |
| B    |     2:15 |
|------+----------|
| Sum  | 03:45:00 |
#+TBLFM: @>$2=vsum(@I..@II);T

Not reproduced (see the known differences): Emacs Lisp formulas ('(...)), which are kept, not evaluated, and named; Calc's full algebra beyond the basic simplifications; complex numbers in polar form and the trigonometric functions of complex numbers, the gamma function, radix, HMS and error forms; a formula that makes Calc overflow shows #ERROR; error messages have Kalem's wording. Calc's named constants pi and e stay symbolic, as they do in Emacs's table formulas ($2=pi*$1 gives pi in both); define them with #+CONSTANTS for a value. Also not reproduced: remote() to a table found by an entry's ID or in another file.

kalem table recalc FILE... recalculates every table with a #+TBLFM line and aligns it, as org-table-recalculate-buffer-tables does; --check changes nothing and fails if a table would change.

The parser reads [cite/style/variant:common prefix; prefix @key suffix; @key2] with every part org-element gives. Bibliographies named by #+BIBLIOGRAPHY: are read as Org reads them (crate org-cite): BibTeX and BibLaTeX as bibtex-parse-entry does, with @string and month abbreviations expanded, and CSL-JSON as oc-basic does. kalem check reports unreadable bibliography files (bibliography-unreadable) and keys that none of them has (cite-unknown-key).

#+CITE_EXPORT: chooses the export processor:

LaTeX fragments and environments are rendered in the editors by the RaTeX engine (crate org-math, decision D4), a KaTeX-compatible layout; \newcommand, \renewcommand, \providecommand, \def and \DeclareMathOperator definitions from #+LATEX_HEADER and #+LATEX_HEADER_EXTRA are applied. A formula the engine cannot render is shown as its source in a red frame. This is display only; the file keeps the LaTeX, and the LaTeX back-end hands it to TeX unchanged.

#+OPTIONS: items are read as Lisp values, as ox.el reads them, with the defaults of Emacs without customizations:

'   *   -   :   <   \n  ^   |   arch   author   broken-links   c
creator   d   date   e   email   expand-links   f   H   inline   num
p   pri   prop   stat   tags   tasks   tex   timestamp   title   toc
todo

Keywords: #+TITLE, #+DATE, #+AUTHOR (parsed as Org text), #+EMAIL, #+LANGUAGE, #+SELECT_TAGS, #+EXCLUDE_TAGS, #+CREATOR, #+SUBTITLE, #+DESCRIPTION, #+KEYWORDS, #+EXPORT_FILE_NAME, #+TOC, #+INCLUDE, #+MACRO, #+SETUPFILE, and #+HTML:, #+LATEX:, #+ASCII: lines for their back-ends. Per back-end:

Also honored: the noexport and export tags, COMMENT subtrees, EXPORT_ properties in subtree export (kalem export --subtree), the UNNUMBERED and ALT_TITLE properties, smart quotes in the document's language (':t), the org-export-dictionary translations, and Babel as when evaluation is refused (:eval never-export): :exports code (the default) writes the block and removes its results, both keeps them, results keeps only the results, none neither; #+CALL: lines and inline calls go (a call to a block the document does not name stops the export, "Unknown Babel reference", as in Emacs), Noweb references expand with :noweb yes. Timestamps are written without custom formats. HTML formulas go to MathJax, or, with tex:svg (and the image types dvisvgm, dvipng and imagemagick, which need LaTeX in Emacs), to inline SVG drawn by the editor's math engine.

Differences in export: macros defined as (eval ...) are Lisp and expand to nothing; Kalem's own style sheet and MathJax set-up replace Org's in whole HTML pages (the comparison skips them); table.el tables spanning columns keep the rows Emacs drops (below); with no #+AUTHOR: no author is written, where Emacs takes user-full-name; the interim Kalem additions are dropped, as Emacs drops them (above).

The expected outputs of the test cases were exported by Emacs 30.1 with Org 9.7.11, except, as the work breakdown records, the whole HTML pages of tests/export/full and the setup-file and subtree cases, which were made with Emacs 29.3 and Org 9.6.15. The comparison of whole pages drops blank lines, and the footnotes and includes pages are expected to differ, since Org 9.7 names footnotes by label where 9.6 numbered them.