docs/manual/guide/04-outlines.org

  1#+TITLE: Outlines and structure
  2#+DESCRIPTION: Headings, subtrees, plain lists, checkboxes, blocks, drawers, properties, column view, footnotes, refiling and archiving.
  3#+LEDE: An org file is an outline of headings with text, lists and drawers under them; this chapter covers the commands that build and rearrange it.
  4
  5Every command in this chapter is in the Org menu and the command palette (=⇧⌘P=),
  6under the title given in the tables, whatever keymap you use. The Org menu shows the
  7keys that run each command in your current keymap.
  8
  9Keys are listed for the three presets. The Emacs and Doom presets use Emacs notation
 10(=M-RET= is Meta-Return, =C-c C-w= is Control-c then Control-w). The Mac preset uses
 11macOS symbols. The Doom preset has every Emacs-preset key that starts with =C-c= or
 12=C-x=, and the =M-=, =S-= arrow and =RET= chords, in normal, insert and visual
 13state, plus the Doom keys listed. Where the Mac column says "menu", the Mac preset has
 14no key for the command; run it from the Org menu or the palette, or bind one in
 15=keymap.toml= (see [[file:03-keys.org][Keys]]).
 16
 17* Headings
 18
 19A heading is a line that starts with one or more stars and a space. The number of stars
 20is its level. A heading and everything under it, down to the next heading at the same
 21or a higher level, is a subtree.
 22
 23#+BEGIN_SRC org
 24,* Project
 25Notes about the project.
 26,** TODO Write the plan
 27,** Meetings
 28,*** Kickoff
 29#+END_SRC
 30
 31** Inserting headings
 32
 33| Command                      | Org command                              | Emacs     | Mac   | Doom      |
 34|------------------------------+------------------------------------------+-----------+-------+-----------|
 35| Insert Heading               | =org-insert-heading=                     | =M-RET=   | =⌘↩=  | =M-RET=   |
 36| Insert Heading After Subtree | =org-insert-heading-respect-content=     | =C-RET=   | =⌃⌘↩= | =C-RET=   |
 37| Insert TODO Heading          | =org-insert-todo-heading=                | =M-S-RET= | =⇧⌘↩= | =M-S-RET= |
 38
 39The new heading has the level of the heading the caret is under, or level 1 before the
 40first heading. In a plain list the same keys insert an item instead (see [[*Plain lists][Plain lists]]).
 41
 42Insert TODO Heading gives the new heading the keyword of the previous heading at the
 43same level when that keyword is not a done state, and otherwise the first keyword of
 44the file's TODO sequence. If the parent has a statistics cookie, it is updated.
 45
 46Two settings change where Insert Heading puts the heading. Both are in Settings ▸
 47Editing and in =config.toml= under the Emacs variable names:
 48
 49| Setting (=config.toml=)              | Settings ▸ Editing                            | Orgstar default | Org default |
 50|--------------------------------------+-----------------------------------------------+-----------------+-------------|
 51| =org-insert-heading-respect-content= | M-RET adds the new heading after the subtree  | =true=          | =nil=       |
 52| =org-M-RET-may-split-line=           | M-RET splits the line at the caret            | =false=         | =t=         |
 53
 54With =org-insert-heading-respect-content= on (the Orgstar default), Insert Heading
 55behaves as Insert Heading After Subtree: the new heading goes after the end of the
 56current subtree, at the current level. Insert Heading also does this when the caret is
 57in folded text.
 58
 59With it off, Insert Heading works where the caret is:
 60
 61- At the start of a heading line, the new heading is inserted above it.
 62- Elsewhere on a heading line, the new heading goes below that line. With
 63  =org-M-RET-may-split-line= on and the caret inside the title, the text after the caret
 64  moves to the new heading. Tags stay on the original line and are realigned.
 65- In body text, a new heading line is started below. With =org-M-RET-may-split-line=
 66  on, the line is split at the caret first.
 67
 68Orgstar follows Org's =org-blank-before-new-entry= default of =auto= for headings: if
 69the heading the caret is in is preceded by a blank line, the new heading is too.
 70
 71Insert Heading After Subtree always inserts after the subtree:
 72
 73#+BEGIN_SRC org
 74,* a
 75body
 76,** b
 77,* c
 78#+END_SRC
 79
 80With the caret on =* a=, =C-RET= gives:
 81
 82#+BEGIN_SRC org
 83,* a
 84body
 85,** b
 86,*
 87,* c
 88#+END_SRC
 89
 90** Promoting and demoting
 91
 92| Command         | Org command          | Emacs         | Mac    | Doom                                      |
 93|-----------------+----------------------+---------------+--------+-------------------------------------------|
 94| Promote Heading | =org-promote=        | =M-<left>=    | =⌃⌘←=  | =M-h=; in insert state =S-TAB= or =C-d=   |
 95| Demote Heading  | =org-demote=         | =M-<right>=   | =⌃⌘→=  | =M-l=; in insert state =TAB= or =C-t=     |
 96| Promote Subtree | =org-promote-subtree= | =M-S-<left>=  | =⌃⌥⌘←= | =M-H=, =SPC m s h=                        |
 97| Demote Subtree  | =org-demote-subtree= | =M-S-<right>= | =⌃⌥⌘→= | =M-L=, =SPC m s l=                        |
 98
 99These run with the caret on a heading line. Promote and Demote Heading change only that
100line's stars; its children keep their level. The subtree commands change the heading and
101every heading under it. Tags are realigned after each change. A level 1 heading can't be
102promoted ("Cannot promote to level 0").
103
104On a list item the same keys indent and outdent the item instead.
105
106** Moving subtrees
107
108| Command           | Org command              | Emacs      | Mac    | Doom              |
109|-------------------+--------------------------+------------+--------+-------------------|
110| Move Subtree Up   | =org-move-subtree-up=    | =M-<up>=   | =⌃⌥⌘↑= | =M-k=, =SPC m s k= |
111| Move Subtree Down | =org-move-subtree-down=  | =M-<down>= | =⌃⌥⌘↓= | =M-j=, =SPC m s j= |
112
113The subtree at the caret swaps places with the previous or next sibling subtree. It
114can't move past its parent or the start or end of the file. The caret keeps its column.
115
116On a list item the same keys move the item; in a table they move the row. On other
117lines they do nothing. Orgstar has no =org-drag-element= for paragraphs.
118
119** Moving between headings
120
121| Command                        | Org command                       | Emacs     | Mac    | Doom              |
122|--------------------------------+-----------------------------------+-----------+--------+-------------------|
123| Next Heading                   | =org-next-visible-heading=        | =C-c C-n= | =⌥⌘↓=  | =C-c C-n=         |
124| Previous Heading               | =org-previous-visible-heading=    | =C-c C-p= | =⌥⌘↑=  | =C-c C-p=         |
125| Next Heading at Same Level     | =org-forward-heading-same-level=  | =C-c C-f= | =⌥⇧⌘↓= | =] h=             |
126| Previous Heading at Same Level | =org-backward-heading-same-level= | =C-c C-b= | =⌥⇧⌘↑= | =[ h=             |
127| Up to Parent Heading           | =outline-up-heading=              | =C-c C-u= | menu   | =g h=             |
128| Go to Heading…                 | =org-goto=                        | =C-c C-j= | menu   | =SPC m .=         |
129
130Next and Previous Heading skip headings that are folded out of sight. The same-level
131commands stop at the parent's boundary. In Doom's normal state, =gj= and =gk= move by
132Org element, as evil-org's =org-forward-element= and =org-backward-element=: on a
133heading line, to the next heading after its subtree, or to the previous heading at the
134same level or higher (see [[file:03-keys.org][Keys and commands]]). Go to Heading asks for a heading by its outline
135path (=Project/Meetings/Kickoff=) with completion, as =org-goto= does with
136=outline-path-completion=.
137
138** Toggling headings, items and comments
139
140| Command         | Org command                                | Emacs   | Mac  | Doom              |
141|-----------------+--------------------------------------------+---------+------+-------------------|
142| Toggle Heading  | =org-toggle-heading=                       | =C-c *= | menu | =SPC m h=         |
143| Toggle Item     | =org-ctrl-c-minus=, =org-toggle-item=      | =C-c -= | menu | =SPC m i=         |
144| Toggle COMMENT  | =org-toggle-comment=                       | =C-c ;= | menu | =C-c ;=           |
145
146These work on the caret's line, or on every line of the selection.
147
148Toggle Heading:
149
150- On headings, removes their stars, so they become text.
151- On list items, turns them into headings one level below the entry they are in. A
152  checkbox becomes a keyword: =[ ]= the first TODO keyword, =[X]= the first done
153  keyword. Nested items become deeper headings.
154- On other lines, makes each non-blank line a heading one level below the current entry.
155  Comment lines are skipped.
156
157#+BEGIN_SRC org
158,* Shopping
159- [ ] milk
160- [X] bread
161#+END_SRC
162
163Selecting both items and pressing =C-c *= gives:
164
165#+BEGIN_SRC org
166,* Shopping
167,** TODO milk
168,** DONE bread
169#+END_SRC
170
171Toggle Item:
172
173- On a list item, with no selection, cycles the list's bullets (see [[*Bullets and numbering][Bullets and numbering]]).
174- On items in a selection, removes their bullets.
175- On headings, turns them into items. The tags, planning line and property drawer are
176  removed. A TODO keyword becomes a checkbox, =[X]= for a done state and =[ ]= otherwise.
177  The section's text is indented under the item.
178- On other lines, puts a =-= bullet and a space in front of each non-blank line.
179
180In a table, =C-c *= recalculates and =C-c -= inserts a horizontal line instead (see
181[[file:10-tables.org][Tables]]).
182
183Toggle COMMENT adds or removes the =COMMENT= keyword after the stars and TODO keyword.
184Commented subtrees are left out of export and column view.
185
186** Selecting a subtree
187
188Mark Subtree (=org-mark-subtree=, =C-c @= in the Emacs and Doom presets) selects the
189subtree at the caret, from its heading line to the end of its last line.
190
191* Subtrees as text
192
193** Cut, copy and paste
194
195| Command       | Org command          | Emacs         | Mac  | Doom                      |
196|---------------+----------------------+---------------+------+---------------------------|
197| Cut Subtree   | =org-cut-subtree=    | =C-c C-x C-w= | menu | =C-c C-x C-w=, =SPC m s d= |
198| Copy Subtree  | =org-copy-subtree=   | =C-c C-x M-w= | menu | =C-c C-x M-w=             |
199| Paste Subtree | =org-paste-subtree=  | =C-c C-x C-y= | menu | =C-c C-x C-y=             |
200
201The kill ring is the system clipboard. Cut Subtree and Copy Subtree put the subtree at
202the caret, with the blank lines after it, on the clipboard and report its length.
203
204Paste Subtree takes the clipboard's text and adjusts its levels to fit where it lands.
205The text has to start with a heading and contain no heading above its first one's
206level; otherwise the command refuses. The level comes from:
207
208- an empty heading line, such as =***= followed by a space, at the caret: that level, and the empty line is
209  replaced;
210- the caret at the start of a heading: that heading's level, pasted before it;
211- otherwise the deeper of the heading above the caret and the heading below it, pasted
212  before the next heading.
213
214** Cloning with a time shift
215
216Clone Subtree with Time Shift (=org-clone-subtree-with-time-shift=, =C-c C-x c=, Doom
217=SPC m s c=) asks for a number of clones, then, if the subtree has timestamps, for a
218shift per clone such as =+1d=, =+1w=, =+2m= or =+1y= (units =h=, =d=, =w=, =m=, =y=).
219Leave the shift empty to copy the dates unchanged.
220
221The clones are inserted after the subtree. The nth clone has its dates moved by n times
222the shift. Clones lose their =CLOCK:= lines, and drawers left empty by that are removed.
223An entry with an =:ID:= property gets a new ID in each clone. When the subtree has a
224repeating timestamp and a shift is given, the repeater is removed from the clones, and
225the original, with its repeater, moves after them with its dates shifted past the last
226clone, as Org does.
227
228** Sorting
229
230Sort Entries (=org-sort=, =C-c ^=, Mac =⌃⇧⌘S=, Doom =SPC m s S=) sorts what the caret is in:
231
232- In a table, the table's lines (=org-table-sort-lines=, see [[file:10-tables.org][Tables]]).
233- On a list item, the items of that list (=org-sort-list=).
234- Otherwise headings (=org-sort-entries=): with a selection, the headings in it;
235  on a heading, its children; before the first heading, the top-level headings.
236
237It then asks for a sort key, one keystroke. A capital letter sorts in reverse.
238
239| Key | Headings                                         | List items                           |
240|-----+--------------------------------------------------+--------------------------------------|
241| =a= | alphabetically by title                          | alphabetically by text               |
242| =n= | numerically by the title's leading number        | numerically by the text              |
243| =p= | priority                                         |                                      |
244| =r= | a property's value (asks which property)         |                                      |
245| =o= | TODO keyword, in sequence order                  |                                      |
246| =t= | first active timestamp, else first timestamp     | first timestamp, or a timer          |
247| =s= | =SCHEDULED= date                                 |                                      |
248| =d= | =DEADLINE= date                                  |                                      |
249| =c= | creation time: the first inactive timestamp at the start of a line |                    |
250| =k= | clocked time in the subtree                      |                                      |
251| =x= |                                                  | checkbox state                       |
252
253Alphabetical and numeric sorts ignore a leading =COMMENT=, link brackets and emphasis
254markers. Sorting is stable, so entries with equal keys keep their order. Entries
255without a date sort as if dated now. After sorting a list, its numbering is repaired.
256Org's =f= (custom function) key is not available.
257
258* Narrowing
259
260| Command                    | Org command                      | Emacs     | Mac  | Doom       |
261|----------------------------+----------------------------------+-----------+------+------------|
262| Narrow to Subtree          | =org-narrow-to-subtree=          | =C-x n s= | menu | =SPC m s n= |
263| Narrow to Block            | =org-narrow-to-block=            | =C-x n b= | menu | =C-x n b=  |
264| Widen                      | =widen=                          | =C-x n w= | menu | =SPC m s N= |
265| Narrow to Subtree or Widen | =org-toggle-narrow-to-subtree=   | speed key =s= | =⌃⌘N=, speed key =s= | speed key =s= |
266
267Narrowing hides everything outside the current subtree or block, so the editor shows
268only that part of the file. Narrow to Block works on src, example, export, comment and
269verse blocks (with the blank lines after them) and, for other blocks, on the lines
270between the opening and closing lines. Edits inside the narrowed text move its bounds
271as you type. Jumping to a position outside it, from a link, search or the outline pane,
272widens first.
273
274Narrowing is a view. Commands still see the whole file: for example, a new footnote's
275definition still goes into the =Footnotes= section at the end of the file, and a sparse
276tree searches the whole file.
277
278* Sparse trees
279
280Sparse Tree… (=org-sparse-tree=, =C-c /=, Doom =SPC m s s=) folds the file to an
281overview and then shows only the matches and the headings above them. It asks what to
282match, one keystroke:
283
284| Key  | Shows                                                                 | Org function           |
285|------+-----------------------------------------------------------------------+------------------------|
286| =r=  | text matching a regular expression (asks for it); case-insensitive    | =org-occur=            |
287| =t=  | headings with a TODO keyword that is not a done state                 | =org-show-todo-tree=   |
288| =T=  | headings with the keywords you give (several separated by a vertical bar) | =org-show-todo-tree=   |
289| =m=  | headings matching a tags and properties match                         | =org-match-sparse-tree= |
290| =p=  | headings where a property has a value (asks for both, with completion) | =org-match-sparse-tree= |
291| =d=  | deadlines past due or due within 14 days (fixed), in entries not done | =org-check-deadlines=  |
292| =b=  | entries with a =SCHEDULED= or =DEADLINE= before a date                | =org-check-before-date= |
293| =a=  | entries with a =SCHEDULED= or =DEADLINE= on or after a date           | =org-check-after-date= |
294| =D=  | entries with a =SCHEDULED= or =DEADLINE= in a date range              | =org-check-dates-range= |
295
296The regular expression uses Emacs syntax. The match syntax for =m= is the one the
297agenda's tags search uses (see [[file:07-agenda.org][Agenda]]). Dates are read as Org reads them (see
298[[file:06-dates-and-clocking.org][Dates and clocking]]).
299
300For a text match, the whole entry around each match is shown; for heading matches,
301the heading line. The matched text is highlighted, and the echo area reports the number
302of matches. Subtrees tagged =ARCHIVE= stay folded. The highlights go away at the next
303edit or with =C-c C-c=. =TAB= and =S-TAB= work as usual afterwards; cycling leaves the
304sparse view.
305
306* Plain lists
307
308Orgstar's list commands are ports of =org-list.el=. A list item starts with a bullet:
309=-=, =+=, =*= (not at the left margin, where it would be a heading), or a number
310followed by =.= or =)=. With alphabetical lists on, =a.=, =A.=, =a)= and =A)= are bullets
311too. A description item has =::= after its term:
312
313#+BEGIN_SRC org
314- milk
315- eggs
316  1. free range
317  2. brown
318- Orgstar :: an org editor for macOS and iOS
319#+END_SRC
320
321| Setting (=config.toml=)       | Settings ▸ Editing               | Orgstar default | Org default |
322|-------------------------------+----------------------------------+-----------------+-------------|
323| =org-list-allow-alphabetical= | Lists can use letters (a. b. c.) | =true=          | =nil=       |
324
325** List commands
326
327| Command                   | Org command              | Emacs         | Mac    | Doom                              |
328|---------------------------+--------------------------+---------------+--------+-----------------------------------|
329| Insert Item               | =org-insert-item=        | =M-RET=       | =⌘↩=   | =M-RET=                           |
330| Insert Checkbox Item      | =org-insert-item= with a checkbox | =M-S-RET= | =⇧⌘↩= | =M-S-RET=                       |
331| Indent Item               | =org-indent-item=        | =M-<right>=   | =⌃⌘→=  | =M-l=; =C-t= in insert state      |
332| Outdent Item              | =org-outdent-item=       | =M-<left>=    | =⌃⌘←=  | =M-h=; =C-d= in insert state      |
333| Indent Item and Children  | =org-indent-item-tree=   | =M-S-<right>= | =⌃⌥⌘→= | =M-L=; =TAB= in insert state      |
334| Outdent Item and Children | =org-outdent-item-tree=  | =M-S-<left>=  | =⌃⌥⌘←= | =M-H=; =S-TAB= in insert state    |
335| Move Item Up              | =org-move-item-up=       | =M-<up>=      | =⌃⌥⌘↑= | =M-k=                             |
336| Move Item Down            | =org-move-item-down=     | =M-<down>=    | =⌃⌥⌘↓= | =M-j=                             |
337| Toggle Checkbox           | =org-toggle-checkbox=    | =C-c C-x C-b= | =⌃⌘C=  | =SPC m x=, =RET= in normal state  |
338| Toggle Item               | =org-ctrl-c-minus=       | =C-c -=       | menu   | =SPC m i=                         |
339
340Insert Item works anywhere inside an item. The new item gets the next bullet: the same
341symbol, the next number or the next letter. In a description list the new item has an
342empty term followed by =::=, with the caret on the term. With =org-M-RET-may-split-line= on, text after the caret moves
343to the new item; with it off (the Orgstar default), the new item goes after the current
344one. At the start of an item, the new item is inserted before it. If the list's items
345are separated by blank lines, so is the new one.
346
347The indent, outdent and move commands need the caret on an item's first line.
348
349- Indent Item and Outdent Item move one item; its children stay where they are, and an
350  item with children can't be outdented alone ("Cannot outdent an item without its
351  children").
352- The "and Children" variants move the item with its sub-items.
353- On the first item of a list, Indent Item refuses; Indent Item and Children and
354  Outdent Item and Children move the whole list. A list moved to the left margin
355  changes =*= bullets to =-=.
356- Move Item Up and Down swap the item, with its children, with the previous or next
357  item at the same level.
358
359After every list command the list is repaired as Org repairs it: bullets are renumbered,
360indentation is fixed and checkboxes of parent items are updated.
361
362** Bullets and numbering
363
364Toggle Item (=C-c -=) on an item, with no selection, cycles the bullet of the whole
365list (=org-cycle-list-bullet=) through:
366
367=-=, =+=, =*=, =1.=, =1)=, then with alphabetical lists =a.=, =A.=, =a)=, =A)=.
368
369=*= is skipped for a list at the left margin. Description lists skip the numbered and
370lettered bullets. Lettered bullets are offered only when the list has 26 items or
371fewer. Org also cycles bullets with =S-<left>= and =S-<right>= on an item; Orgstar
372does not bind those on items.
373
374Numbered and lettered lists are renumbered whenever a list command changes them, and
375by =C-c C-c= on any item. To start a list at a given number, put a counter after the
376bullet, as in Org:
377
378#+BEGIN_SRC org
3795. [@5] fifth
3806. sixth
381#+END_SRC
382
383* Checkboxes and statistics
384
385** Checkboxes
386
387An item with =[ ]= after its bullet has a checkbox. =[X]= is checked, and =[-]= marks a
388parent item whose children are partly checked.
389
390#+BEGIN_SRC org
391- [-] packing
392  - [X] passport
393  - [ ] charger
394#+END_SRC
395
396Toggle Checkbox (=C-c C-x C-b=) checks or unchecks the item on the caret's line, or
397every item in the selection. =C-c C-c= on an item toggles its checkbox too, and on an
398item without one, repairs the list. A parent item's checkbox follows its children: it
399can't be checked while children are unchecked ("Cannot toggle this checkbox: unchecked
400subitems").
401
402Toggle Checkbox works only on item lines. Org's behaviour on a heading, toggling the
403checkboxes of the region or subtree, is not available.
404
405** Statistics cookies
406
407A cookie =[/]= or =[%]= on a heading or an item shows progress:
408
409- On an item, it counts that item's direct child checkboxes.
410- On a heading, it counts the checkboxes of the top-level items in the heading's own
411  section. If the section has none, it counts the TODO children: direct child headings
412  with a keyword, and how many of them are in a done state.
413
414#+BEGIN_SRC org
415,* Groceries [1/3]
416- [X] milk
417- [ ] eggs
418- [ ] bread
419
420,* Release [50%]
421,** DONE Tag the build
422,** TODO Write the notes
423#+END_SRC
424
425Cookies update when you toggle or insert a checkbox, when a child heading's TODO state
426changes, when you archive an entry, and when you press =C-c C-c= with the caret on the
427cookie. A cookie with nothing to count shows =[0/0]= or =[100%]=. Tags are realigned when
428the cookie's width changes.
429
430The =COOKIE_DATA= property changes what a heading's cookie counts, as in Org:
431
432| Value       | Effect                                                         |
433|-------------+----------------------------------------------------------------|
434| =todo=      | count TODO children, not checkboxes                            |
435| =checkbox=  | count checkboxes, not TODO children                            |
436| =recursive= | count all descendants, not only direct children                |
437
438For TODO statistics, =COOKIE_DATA= is read with inheritance, from the parent or an
439ancestor. Orgstar counts TODO children hierarchically, as Org does with
440=org-hierarchical-todo-statistics= at its default.
441
442* Blocks
443
444Blocks are lines between =#+BEGIN_name= and =#+END_name=:
445
446#+BEGIN_SRC org
447,#+BEGIN_QUOTE
448Text to quote.
449,#+END_QUOTE
450#+END_SRC
451
452** Structure templates
453
454Insert Structure Template (=org-insert-structure-template=, =C-c C-,= in the Emacs and
455Doom presets) asks for a block type, one keystroke:
456
457| Key | Block           |
458|-----+-----------------|
459| =a= | =export ascii=  |
460| =c= | =center=        |
461| =C= | =comment=       |
462| =e= | =example=       |
463| =E= | =export=        |
464| =h= | =export html=   |
465| =l= | =export latex=  |
466| =q= | =quote=         |
467| =s= | =src=           |
468| =v= | =verse=         |
469
470Press =TAB= to type any other type. These are Org's default
471=org-structure-template-alist=; Orgstar does not read a custom one. The block is
472inserted at the caret's indentation. With a selection, the block wraps the selected
473lines, and for =src=, =example=, =export= and =comment= blocks, lines that would read as
474headings or keywords are protected with a leading comma. For =src= and =export=, the
475caret ends on the opening line after a space, ready for the language; otherwise it ends
476inside the block. The case of =BEGIN= and =END= follows the case of the type you typed.
477
478** org-tempo templates
479
480Typing =<= and a key at the start of a line (after blanks only) and then completing
481expands it as =org-tempo= does. =<s= becomes:
482
483#+BEGIN_SRC org
484,#+begin_src
485,#+end_src
486#+END_SRC
487
488with the caret after =begin_src=. The keys are those of the table above, plus =<L=,
489=<H=, =<A= and =<i=, which insert =#+latex:=, =#+html:=, =#+ascii:= and =#+index:=
490keyword lines.
491
492Completion runs with Complete at Point (=C-M-i= in the Emacs preset, =C-SPC= in Doom's
493insert state; in the Mac preset, from the palette). In the Doom preset the completion
494list also opens by itself after a short pause once you have typed =<= and a letter, and
495=TAB= or =RET= takes the selected candidate. =TAB= alone does not expand =<s= in the
496Emacs or Mac preset.
497
498** Folding and editing blocks
499
500=TAB= on a block's first or last line folds or unfolds it. Blocks are open when a file
501opens unless =org-cycle-hide-block-startup= is on in =config.toml= or the file has
502=#+STARTUP: hideblocks= (=nohideblocks= overrides the setting the other way). See
503[[file:02-the-editor.org][The editor]] for folding in general.
504
505Edit Block (=org-edit-special=, =C-c '=, Mac =⌃⌘'=) edits a src, example or export block in a
506separate editor. See [[file:11-code-blocks.org][Code blocks]].
507
508* Drawers
509
510A drawer is a named group of lines between =:NAME:= and =:END:=. Orgstar writes the
511=PROPERTIES= drawer for properties and, depending on =org-log-into-drawer=, a =LOGBOOK=
512drawer for state notes and clock lines (see [[file:05-todos-and-tags.org][TODOs and tags]] and
513[[file:06-dates-and-clocking.org][Dates and clocking]]). You can write any other drawer by hand:
514
515#+BEGIN_SRC org
516,* Meeting
517:NOTES:
518Private notes, folded away.
519:END:
520#+END_SRC
521
522=TAB= on a drawer's first or last line folds or unfolds it. Drawers are folded when a
523file opens, as with Org's =org-cycle-hide-drawer-startup= (=true= by default in
524=config.toml=). =#+STARTUP: nohidedrawers= keeps them open in one file, and
525=#+STARTUP: hidedrawers= folds them when the setting is off.
526
527Org's =org-insert-drawer= (=C-c C-x d=) is not available; type the two lines yourself.
528
529* Properties
530
531Properties are key-value pairs in an entry's =PROPERTIES= drawer, right after the
532heading and its planning line:
533
534#+BEGIN_SRC org
535,* Laptop
536:PROPERTIES:
537:VENDOR:   Apple
538:Effort:   1:00
539:END:
540#+END_SRC
541
542File-wide properties come from =#+PROPERTY:= lines and from a =PROPERTIES= drawer before
543the first heading. A key written =KEY+= appends its value to the inherited one with a
544space between.
545
546** Setting and deleting
547
548| Command                     | Org command                     | Emacs       | Mac  | Doom       |
549|-----------------------------+---------------------------------+-------------+------+------------|
550| Set Property…               | =org-set-property=              | =C-c C-x p= | =⌃⇧⌘P= | =SPC m o=  |
551| Delete Property…            | =org-delete-property=           | none        | menu | none       |
552| Delete Property Everywhere… | =org-delete-property-globally=  | none        | menu | none       |
553| Property Action…            | =org-property-action=           | =C-c C-c= in a property drawer | =⌃⌘X= in a property drawer | =C-c C-c= |
554| Next Allowed Value          | =org-property-next-allowed-value= | =S-<right>= on a property line | =⌃⇧⌘→= on a property line | =S-<right>=, =C-S-l= |
555| Previous Allowed Value      | =org-property-previous-allowed-value= | =S-<left>= on a property line | =⌃⇧⌘←= on a property line | =S-<left>=, =C-S-h= |
556
557Set Property asks for the key, offering the keys used in the file, Org's standard keys
558and the properties named in =COLUMNS= formats; on a property line, Return takes that
559line's key. It then asks for the value. If the key has allowed values, those are
560offered and required unless the list includes =:ETC=; otherwise the values the key has
561elsewhere in the file are offered. An empty answer keeps the current value. The drawer
562is created if the entry has none, and lines are aligned as Org's
563=org-property-format= (="%-10s %s"=) aligns them. Setting =TODO= sets the entry's TODO
564keyword instead.
565
566Delete Property asks which of the entry's properties to remove, when it has more than
567one, and removes the drawer if it becomes empty. Delete Property Everywhere removes a key
568from every entry in the file and reports how many it changed. Property Action, run by
569=C-c C-c= in a property drawer, asks =s= (set), =d= (delete) or =D= (delete everywhere).
570
571** Allowed values
572
573A property =KEY_ALL= lists the values =KEY= may take, separated by spaces, with quotes
574around values that contain spaces. Orgstar looks for it on the entry, then its
575ancestors, then the file:
576
577#+BEGIN_SRC org
578,#+PROPERTY: Status_ALL open blocked done
579#+END_SRC
580
581Next and Previous Allowed Value step through the list on a property line. =TODO= and
582=PRIORITY= take their values from the file's keywords and priority range. A property
583whose value is =[ ]= or =[X]= toggles between them.
584
585** Inheritance
586
587Orgstar inherits properties as Org does with =org-use-property-inheritance= at its
588default of =nil=: a property applies only to the entry that has it, with these
589exceptions:
590
591- =CATEGORY=, =ARCHIVE=, =COLUMNS=, =LOGGING= and the =header-args= properties are
592  always inherited from ancestors and =#+PROPERTY:= lines.
593- =ID= and =CUSTOM_ID= are never inherited.
594- =KEY_ALL= allowed values and =COOKIE_DATA= for TODO statistics are looked up through
595  the ancestors.
596
597Orgstar has no setting for =org-use-property-inheritance=.
598
599** Special properties
600
601Org computes some properties instead of reading them from a drawer. Orgstar treats
602these as special and doesn't offer them as allowed-value lists: =ALLTAGS=, =BLOCKED=,
603=CLOCKSUM=, =CLOCKSUM_T=, =CLOSED=, =DEADLINE=, =FILE=, =ITEM=, =PRIORITY=, =SCHEDULED=,
604=TAGS=, =TIMESTAMP=, =TIMESTAMP_IA= and =TODO=. Column view computes =ITEM=, =TODO=,
605=PRIORITY=, =TAGS=, =ALLTAGS=, =DEADLINE=, =SCHEDULED=, =CLOSED= and =CLOCKSUM=; the
606others show as empty there.
607
608* Column view
609
610Column view shows entries as rows and properties as columns. The columns come from a
611=COLUMNS= format, found in this order:
612
6131. a =COLUMNS= property on the entry at the caret or one of its ancestors (the nearest
614   one wins, and that entry becomes the top of the view);
6152. a =#+COLUMNS:= line in the file;
6163. Org's default, =%25ITEM %TODO %3PRIORITY %TAGS=.
617
618#+BEGIN_SRC org
619,#+COLUMNS: %40ITEM %TODO %Effort(Estimate){:} %CLOCKSUM
620#+END_SRC
621
622Each column is =%[width]PROPERTY[(title)][{summary}]=, as in Org. The width limits the
623column, the title replaces the property name in the header, and the summary is computed
624for parent entries from their children. The summary operators are =+=, =$=, =min=,
625=max=, =mean=, =X=, =X/=, =X%=, =:=, =:min=, =:max=, =:mean= and =est+=. Org's age
626operators (=@min=, =@max=, =@mean=) are not supported. The numeric operators take a
627format after a semicolon, as in ={+;%.1f}=.
628
629Subtrees tagged =ARCHIVE= and commented subtrees are left out.
630
631** The column view sheet
632
633| Command             | Org command               | Emacs         | Mac  | Doom          |
634|---------------------+---------------------------+---------------+------+---------------|
635| Column View         | =org-columns=             | =C-c C-x C-c= | menu | =C-c C-x C-c= |
636| Column View of File | =org-columns= with a prefix | none        | menu | none          |
637
638Column View opens a sheet with the entries from the view's top (the entry with the
639=COLUMNS= property, or the entry at the caret; the whole file before the first
640heading). Column View of File shows every entry in the file. Click a row to go to its
641heading. Done (or Escape) closes the sheet.
642
643The sheet is read-only. Org's column view lets you edit values in place and writes
644parent summaries back into the file; Orgstar's does neither. Change values with Set
645Property, or edit the drawer.
646
647** The Columns inspector
648
649View ▸ Show or Hide Columns and Clock opens an inspector beside the editor. Its Columns
650tab shows the same table for the open file, kept current as you type. Choose File for
651every entry or Subtree for the entry at the caret. The row of the heading at the caret
652is shown in bold, and clicking a row goes to it. The Clock tab is described in
653[[file:06-dates-and-clocking.org][Dates and clocking]].
654
655** Column view tables
656
657Insert Column View Table (=org-columns-insert-dblock=, =C-c C-x i=) asks what to
658capture: =local= (the default, the entry at the caret), =global= (the whole file) or an
659=ID= of an entry. It inserts a =columnview= dynamic block and fills it:
660
661#+BEGIN_SRC org
662,#+BEGIN: columnview :hlines 1 :id local
663| ITEM | TODO | PRIORITY | TAGS |
664|------+------+----------+------|
665| ...  |      |          |      |
666,#+END:
667#+END_SRC
668
669=C-c C-c= (Mac =⌃⌘X=) on the =#+BEGIN:= line, or =C-c C-x C-u= anywhere in the block, updates it.
670Updating writes summary values into the parents' properties, as Org does. The block
671takes these parameters:
672
673| Parameter          | Meaning                                                           |
674|--------------------+-------------------------------------------------------------------|
675| =:id=              | =local=, =global=, or an entry's =ID=                             |
676| =:format=          | a column format to use instead of the entry's or file's           |
677| =:hlines=          | =t= for a line between all rows, or N for one before each level N or higher row |
678| =:maxlevel=        | leave out deeper headings                                         |
679| =:skip-empty-rows= | leave out rows whose columns other than =ITEM= are empty          |
680| =:exclude-tags=    | leave out entries with these tags, as a list                      |
681| =:indent=          | indent =ITEM= by level                                            |
682
683Existing =#+TBLFM:= lines after the table are kept. An =:id= of the form =file:path=
684(another file) is not supported.
685
686* Footnotes
687
688| Command         | Org command          | Emacs       | Mac  | Doom        |
689|-----------------+----------------------+-------------+------+-------------|
690| Footnote Action | =org-footnote-action= | =C-c C-x f= | =⌃⇧⌘F= | =C-c C-x f= |
691| Footnote Menu   | =org-footnote-action= with a prefix | none | menu | none |
692
693Footnote Action depends on where the caret is:
694
695- On a reference such as =[fn:1]=, it goes to the definition. If there is none, it asks
696  whether to create one.
697- On a definition's label, it goes back to a reference.
698- Elsewhere, where a footnote is allowed, it inserts a new reference with the next free
699  number and creates its definition.
700- Where a footnote can't go, it shows the footnote menu.
701
702=C-c C-c= on a reference or a definition's label does the same jumps. After a jump to a
703definition, the echo area says how to get back:
704=Edit definition and go back with `C-c C-c' or `C-c C-x f' on its label.=
705
706New definitions go in a level 1 heading named =Footnotes= at the end of the file, which
707is created when needed (Org's =org-footnote-section=):
708
709#+BEGIN_SRC org
710,* Notes
711Orgstar reads org files.[fn:1]
712
713,* Footnotes
714
715[fn:1] And writes them.
716#+END_SRC
717
718The footnote menu asks, one keystroke:
719
720| Key | Action                                                                     | Org function                 |
721|-----+----------------------------------------------------------------------------+------------------------------|
722| =s= | sort definitions into the order of their first reference                   | =org-footnote-sort=          |
723| =r= | renumber numeric labels =fn:N= in order of appearance                     | =org-footnote-renumber-fn:N= |
724| =S= | renumber, then sort                                                        |                              |
725| =n= | normalize: number every footnote, labeled, anonymous and inline, and collect all definitions in the footnote section | =org-footnote-normalize= |
726| =d= | delete the footnote at the caret: its references and definition           | =org-footnote-delete=        |
727
728A reference with no definition gets the text =DEFINITION NOT FOUND.= when sorted or
729normalized.
730
731* Refiling
732
733Refile… (=org-refile=, =C-c C-w=, Mac =⌃⌘W=, Doom =SPC m r r= or =SPC m s r=) moves the
734subtree at the caret under another heading, in this file or another one.
735
736It asks for the target with completion. The targets are every org file in your folders
737and every heading down to level 3 in those files, written as the file's path relative
738to its folder followed by the outline path:
739
740#+BEGIN_EXAMPLE
741projects.org
742projects.org/Work
743projects.org/Work/Website
744notes/inbox.org/Someday
745#+END_EXAMPLE
746
747Choosing a heading makes the subtree its last child, at one level below it. Choosing a
748file adds the subtree at the end of that file as a level 1 heading. Levels inside the
749subtree are shifted to match, and tags are realigned. A subtree can't be refiled into
750itself.
751
752For the open file, targets come from the buffer, including unsaved edits. When the
753target is another file, Orgstar writes that file first, into its open buffer if it has
754one, otherwise through the normal save path, and removes the subtree from the source
755only after that succeeds. If the target file changed on disk in the meantime, nothing
756is refiled.
757
758This matches Org with =org-refile-targets= set to headings of maximum level 3 in all
759files, =org-refile-use-outline-path= set to =file=, =org-reverse-note-order= =nil= (new
760entries go last), =org-log-refile= =nil= and =org-refile-keep= =nil=. None of these is
761configurable in Orgstar. Refiling from the agenda is covered in [[file:07-agenda.org][Agenda]].
762
763* Archiving
764
765** Archive Subtree
766
767Archive Subtree (=org-archive-subtree=, =C-c C-x C-s= or =C-c $=, Mac =⌃⌘A=, Doom
768=SPC m A= or =SPC m s A=) moves the subtree at the caret to an archive.
769
770The archive location is read from, in order: the =ARCHIVE= property of the entry or an
771ancestor, a =#+ARCHIVE:= line in the file, and Org's default =%s_archive::=. A location
772is =file::heading=, where =%s= stands for the current file's name:
773
774| Location               | Where the subtree goes                                                     |
775|------------------------+----------------------------------------------------------------------------|
776| =%s_archive::=         | the end of =notes.org_archive= next to =notes.org=, at level 1             |
777| =archive.org::* Old=   | under the heading =* Old= in =archive.org=, created if missing             |
778| =::* Archived=         | under =* Archived= in the same file                                        |
779| =%s_archive::datetree/= | under year, month and day headings in the archive file, for the entry's =CLOSED= date or today |
780
781Relative paths are relative to the current file's folder, and =~= is your home folder. A
782new archive file starts with a line =Archived entries from file= followed by the
783source's path.
784
785The archived entry gets these properties, as with Org's default
786=org-archive-save-context-info=: =ARCHIVE_TIME=, =ARCHIVE_FILE=, =ARCHIVE_OLPATH=,
787=ARCHIVE_CATEGORY=, =ARCHIVE_TODO= and =ARCHIVE_ITAGS= (empty ones are left out).
788Within the same file, tags it inherited are added to its heading. After the subtree
789leaves, the parent's statistics cookies are updated. The entry's TODO state is not
790changed.
791
792If the archive file is open, the subtree goes into its buffer. Otherwise Orgstar writes
793the archive file first and removes the subtree from the source only after that
794succeeds. Org's option =org-archive-location= in Emacs is not read; use the =ARCHIVE=
795property or =#+ARCHIVE:=. Archiving from the agenda is covered in [[file:07-agenda.org][Agenda]].
796
797** The ARCHIVE tag
798
799Toggle ARCHIVE Tag (=org-toggle-archive-tag=, =C-c C-x a=, Doom =SPC m s a=) adds or
800removes the =ARCHIVE= tag on the entry at the caret. Adding it folds the subtree.
801
802Subtrees tagged =ARCHIVE= stay where they are, but are folded when a file opens and in
803sparse trees, and are left out of column view. =TAB= opens an archived subtree like
804any other; Org's =org-cycle-open-archived-trees= behaviour, which keeps them closed, is
805not reproduced. See [[file:05-todos-and-tags.org][TODOs and tags]] for tags in general.
806
807** Archive sibling
808
809Archive to Archive Sibling (=org-archive-to-archive-sibling=, =C-c C-x A=) moves the
810subtree at the caret under a sibling heading named =Archive= with the =ARCHIVE= tag,
811creating it at the end of the parent's children if needed. The moved entry gets an
812=ARCHIVE_TIME= property, and the =Archive= sibling is folded.
813
814* The outline pane
815
816The outline pane, to the left of the editor, lists the headings of the open org file,
817indented by level. Click a heading to go to it; folded text around it opens. A heading
818with no title is shown as =(untitled)=.
819
820Show or hide it with the toolbar button or View ▸ Show or Hide Outline. Orgstar
821remembers the choice for org files; for other files the pane starts hidden and shows
822"Only org files have an outline." Drag the divider to resize it. While the search field
823has text, the pane shows search results instead. The backlinks pane, when shown, sits
824below the outline (see [[file:09-links.org][Links]]).
825
826* C-c C-c
827
828=C-c C-c= (=org-ctrl-c-ctrl-c=) does what fits the caret's position. In the Emacs and
829Doom presets it is =C-c C-c=; in the Mac preset it is =⌃⌘X=. In order, it:
830
831| Caret on                                   | Effect                                                     |
832|--------------------------------------------+------------------------------------------------------------|
833| anywhere, while sparse tree highlights show | removes the highlights, and nothing else (not in a table or src block) |
834| a src block, a =#+CALL= line or inline code | runs it (see [[file:11-code-blocks.org][Code blocks]])                            |
835| a table or =#+TBLFM= line                  | aligns the table, or recalculates it (see [[file:10-tables.org][Tables]])          |
836| a footnote reference or definition label   | jumps between them                                         |
837| a blank line                               | nothing                                                    |
838| a =CLOCK:= line                            | fixes the weekdays and writes the duration again           |
839| a dynamic block's =#+BEGIN:= line          | updates the block                                          |
840| a statistics cookie                        | updates it                                                 |
841| a timestamp                                | fixes its weekday                                          |
842| a heading                                  | sets tags (see [[file:05-todos-and-tags.org][TODOs and tags]])                       |
843| a list item                                | toggles its checkbox, repairs the list and updates cookies |
844| a =#+KEYWORD:= line                        | rereads the file's settings and =#+SETUPFILE=              |
845| a property drawer                          | runs Property Action                                       |
846
847Elsewhere it reports that it can do nothing useful.
848
849In the Doom preset, =RET= in normal state runs Doom's =+org/dwim-at-point= instead. It
850follows a link, recalculates a table with formulas or aligns one without, runs a src
851block, toggles an item's checkbox, or on a heading switches between the first TODO and
852first done keyword of its sequence.
853
854* Speed keys
855
856With =org-use-speed-commands= set to =true= in =config.toml=, single keys run commands when the
857caret is at the very start of a heading line, before the stars. These are Org's
858=org-speed-commands=; the structure ones are:
859
860| Key | Command                       | Key | Command                    |
861|-----+-------------------------------+-----+----------------------------|
862| =n= | Next Heading                  | =U= | Move Subtree Up            |
863| =p= | Previous Heading              | =D= | Move Subtree Down          |
864| =f= | Next Heading at Same Level    | =r= | Demote Heading             |
865| =b= | Previous Heading at Same Level | =l= | Promote Heading           |
866| =u= | Up to Parent Heading          | =R= | Demote Subtree             |
867| =j= | Go to Heading…                | =L= | Promote Subtree            |
868| =s= | Narrow to Subtree or Widen    | =i= | Insert Heading After Subtree |
869| =k= | Cut Subtree                   | =^= | Sort Entries               |
870| =@= | Mark Subtree                  | =w= | Refile…                    |
871| =#= | Toggle COMMENT                | =a= | Archive Subtree            |
872| =/= | Sparse Tree…                  | =c=, =C= | cycle visibility, cycle global visibility |
873
874The full list is in [[file:03-keys.org][Keys]].
875
876* Not supported
877
878These Org structure features are not in Orgstar:
879
880- =org-insert-drawer=, =org-copy= (refile a copy) and =org-refile= with a prefix
881  (jump to a target).
882- Editing values in column view, and writing summaries from it; the
883  =columnview= dynamic block does write summaries.
884- The =ORDERED= property, radio lists and timer list items in the list commands.
885- =S-<left>= and =S-<right>= to cycle bullets on an item; use =C-c -=.
886- =org-drag-element= (=M-<up>= and =M-<down>= on paragraphs).
887- Custom =org-structure-template-alist=, =org-refile-targets=, =org-archive-location=
888  and =org-use-property-inheritance=.