Spec map

Use this mapping when deciding where behavior is defined:

• Core syntax and canonical AST: spec/v0/SPEC.org

• Roam semantics (IDs, links, backlinks model): spec/v0/ROAM.org

• CLI/editor workflow behavior: Tooling reference

Headings

• Syntax: one or more stars, a space, then title text.

• Example:

* Project
** Subproject
*** Task

• Heading level is the number of stars.

• Level skips are accepted in v0.

TODO keywords

Headline TODO states parsed by Org2 workflows:

• TODO

• IN_PROGRESS

• PROG

• DONE

• CANCELLED / CANCELED

Example:

* TODO Ship docs
* IN_PROGRESS Implement parser tests
* DONE Publish changelog

Priority cookies

• Syntax: [#A] style cookie after TODO keyword (or at headline start when no TODO keyword).

* TODO [#A] Critical task

Tags

• Tags are suffixes at headline end: :tag: or :tag1:tag2:

* TODO Draft docs :docs:website:

Drawers

:PROPERTIES:
:ID: 123e4567-e89b-12d3-a456-426614174000
:EFFORT: 45
:END:

Planning lines

Recognized planning keywords:

• SCHEDULED:

• DEADLINE:

• CLOSED:

SCHEDULED: <2026-02-21 Sat>
DEADLINE: <2026-02-25 Wed>
CLOSED: [2026-02-20 Fri]

Timestamps

Supported timestamp forms:

• Active: <2026-02-21 Sat>

• Inactive: [2026-02-21 Sat]

• With time: <2026-02-21 Sat 09:30>

• Ranges: <2026-02-21 Sat>--<2026-02-23 Mon>

• Repeaters (agenda projection): +1w, ++1m, .+2d

Lists

• Unordered markers: -, +, *

• Ordered markers: 1., 1)

• Checkboxes: [ ], [X], [-]

• Nested lists via indentation.

Links

Supported link forms:

• Bracket links: [[https://example.com][label]]

• Plain URLs: https://example.com

• File links: [[file:path/to/file.org]]

• ID links: [[id:UUID][label]] (roam-style link)

• Wiki links: [[Node Title]] (roam-style link)

Both ID links and Wiki links are first-class in Org2 roam workflows.

Link abbreviations are supported with built-ins, config, and #+LINK directives.

Built-in abbreviations:

• gh: → https://github.com/%s

• gl: → https://gitlab.com/%s

• yt: → https://www.youtube.com/watch?v%s=

• wiki: → https://en.wikipedia.org/wiki/%s

You can add/override abbreviations in org2.json:

{
  "links": {
    "linearTeam": "scarf",
    "abbreviations": {
      "linear": "https://linear.app/scarf/issue/%s",
      "gh": "https://github.example.com/%s"
    }
  }
}

And define file-local abbreviations with Org-compatible syntax:

• Define: #+LINK: linear https://linear.app/scarf/issue/%s

• Use: [[linear:APP-3718][APP-3718]] or [[linear:APP-3718]]

Precedence (highest to lowest):

1. file-local #+LINK

2. org2.json links.abbreviations

3. built-ins

Org2 expands abbreviation targets when rendering/exporting and for LSP document-link targets.

Inline emphasis

• Bold: *bold*

• Italic: /italic/

• Underline: _underline_

• Strike: +strike+

• Verbatim: =verbatim=

• Code: ~code~

Blocks

Recognized block forms include:

• Source blocks: #+begin_src ... #+end_src

• Example blocks: #+begin_example ... #+end_example

• Quote blocks: #+begin_quote ... #+end_quote

• Verse blocks: #+begin_verse ... #+end_verse

• Center blocks: #+begin_center ... #+end_center

• Comment blocks: #+begin_comment ... #+end_comment

```ts
const x = 1
```

#+begin_src ts
const x = 1

#+end_src

Tables

• Pipe table rows: | a | b |

• Horizontal separator rows: |---+---|

• Table content is parsed and preserved.

Keyword/directive lines

Org2 parses keyword lines in #+KEY: VALUE form.

Commonly used in export/publish:

• #+TITLE:

• #+SUBTITLE:

• #+AUTHOR:

• #+DATE:

• #+DESCRIPTION:

• #+KEYWORDS:

• #+LANGUAGE:

• #+HTML_HEAD:

• #+ID:

Unknown directives are preserved for round-tripping.

Comments

• Line comments: lines beginning with #.

• Comment blocks are also supported (see Blocks).

Losslessness goal

Org2 aims for practical round-tripping of supported constructs. When behavior is ambiguous, defer to the current implementation and spec fixtures.