docs/manual/guide/04-outlines.org

The new heading has the level of the heading the caret is under, or level 1 before the first heading. In a plain list the same keys insert an item instead (see Plain lists).

Insert TODO Heading gives the new heading the keyword of the previous heading at the same level when that keyword is not a done state, and otherwise the first keyword of the file's TODO sequence. If the parent has a statistics cookie, it is updated.

Two settings change where Insert Heading puts the heading. Both are in Settings ▸ Editing and in config.toml under the Emacs variable names:

With org-insert-heading-respect-content on (the Orgstar default), Insert Heading behaves as Insert Heading After Subtree: the new heading goes after the end of the current subtree, at the current level. Insert Heading also does this when the caret is in folded text.

With it off, Insert Heading works where the caret is:

• At the start of a heading line, the new heading is inserted above it.
• Elsewhere on a heading line, the new heading goes below that line. With org-M-RET-may-split-line on and the caret inside the title, the text after the caret moves to the new heading. Tags stay on the original line and are realigned.
• In body text, a new heading line is started below. With org-M-RET-may-split-line on, the line is split at the caret first.

Orgstar follows Org's org-blank-before-new-entry default of auto for headings: if the heading the caret is in is preceded by a blank line, the new heading is too.

Insert Heading After Subtree always inserts after the subtree:

* a
body
** b
* c

With the caret on * a, C-RET gives:

* a
body
** b
*
* c

These run with the caret on a heading line. Promote and Demote Heading change only that line's stars; its children keep their level. The subtree commands change the heading and every heading under it. Tags are realigned after each change. A level 1 heading can't be promoted ("Cannot promote to level 0").

On a list item the same keys indent and outdent the item instead.

The subtree at the caret swaps places with the previous or next sibling subtree. It can't move past its parent or the start or end of the file. The caret keeps its column.

On a list item the same keys move the item; in a table they move the row. On other lines they do nothing. Orgstar has no org-drag-element for paragraphs.

Next and Previous Heading skip headings that are folded out of sight. The same-level commands stop at the parent's boundary. In Doom's normal state, gj and gk move by Org element, as evil-org's org-forward-element and org-backward-element: on a heading line, to the next heading after its subtree, or to the previous heading at the same level or higher (see Keys and commands). Go to Heading asks for a heading by its outline path (Project/Meetings/Kickoff) with completion, as org-goto does with outline-path-completion.

These work on the caret's line, or on every line of the selection.

Toggle Heading:

• On headings, removes their stars, so they become text.
• On list items, turns them into headings one level below the entry they are in. A checkbox becomes a keyword: [ ] the first TODO keyword, [X] the first done keyword. Nested items become deeper headings.
• On other lines, makes each non-blank line a heading one level below the current entry. Comment lines are skipped.

* Shopping
- [ ] milk
- [X] bread

Selecting both items and pressing C-c * gives:

* Shopping
** TODO milk
** DONE bread

Toggle Item:

• On a list item, with no selection, cycles the list's bullets (see Bullets and numbering).
• On items in a selection, removes their bullets.
• On headings, turns them into items. The tags, planning line and property drawer are removed. A TODO keyword becomes a checkbox, [X] for a done state and [ ] otherwise. The section's text is indented under the item.
• On other lines, puts a - bullet and a space in front of each non-blank line.

In a table, C-c * recalculates and C-c - inserts a horizontal line instead (see Tables).

Toggle COMMENT adds or removes the COMMENT keyword after the stars and TODO keyword. Commented subtrees are left out of export and column view.

Mark Subtree (org-mark-subtree, C-c @ in the Emacs and Doom presets) selects the subtree at the caret, from its heading line to the end of its last line.

The kill ring is the system clipboard. Cut Subtree and Copy Subtree put the subtree at the caret, with the blank lines after it, on the clipboard and report its length.

Paste Subtree takes the clipboard's text and adjusts its levels to fit where it lands. The text has to start with a heading and contain no heading above its first one's level; otherwise the command refuses. The level comes from:

• an empty heading line, such as *** followed by a space, at the caret: that level, and the empty line is replaced;
• the caret at the start of a heading: that heading's level, pasted before it;
• otherwise the deeper of the heading above the caret and the heading below it, pasted before the next heading.

Clone Subtree with Time Shift (org-clone-subtree-with-time-shift, C-c C-x c, Doom SPC m s c) asks for a number of clones, then, if the subtree has timestamps, for a shift per clone such as +1d, +1w, +2m or +1y (units h, d, w, m, y). Leave the shift empty to copy the dates unchanged.

The clones are inserted after the subtree. The nth clone has its dates moved by n times the shift. Clones lose their CLOCK: lines, and drawers left empty by that are removed. An entry with an :ID: property gets a new ID in each clone. When the subtree has a repeating timestamp and a shift is given, the repeater is removed from the clones, and the original, with its repeater, moves after them with its dates shifted past the last clone, as Org does.

Sort Entries (org-sort, C-c ^, Mac ⌃⇧⌘S, Doom SPC m s S) sorts what the caret is in:

• In a table, the table's lines (org-table-sort-lines, see Tables).
• On a list item, the items of that list (org-sort-list).
• Otherwise headings (org-sort-entries): with a selection, the headings in it; on a heading, its children; before the first heading, the top-level headings.

It then asks for a sort key, one keystroke. A capital letter sorts in reverse.

Alphabetical and numeric sorts ignore a leading COMMENT, link brackets and emphasis markers. Sorting is stable, so entries with equal keys keep their order. Entries without a date sort as if dated now. After sorting a list, its numbering is repaired. Org's f (custom function) key is not available.

Insert Item works anywhere inside an item. The new item gets the next bullet: the same symbol, the next number or the next letter. In a description list the new item has an empty term followed by ::, with the caret on the term. With org-M-RET-may-split-line on, text after the caret moves to the new item; with it off (the Orgstar default), the new item goes after the current one. At the start of an item, the new item is inserted before it. If the list's items are separated by blank lines, so is the new one.

The indent, outdent and move commands need the caret on an item's first line.

• Indent Item and Outdent Item move one item; its children stay where they are, and an item with children can't be outdented alone ("Cannot outdent an item without its children").
• The "and Children" variants move the item with its sub-items.
• On the first item of a list, Indent Item refuses; Indent Item and Children and Outdent Item and Children move the whole list. A list moved to the left margin changes * bullets to -.
• Move Item Up and Down swap the item, with its children, with the previous or next item at the same level.

After every list command the list is repaired as Org repairs it: bullets are renumbered, indentation is fixed and checkboxes of parent items are updated.

Toggle Item (C-c -) on an item, with no selection, cycles the bullet of the whole list (org-cycle-list-bullet) through:

-, +, *, 1., 1), then with alphabetical lists a., A., a), A).

* is skipped for a list at the left margin. Description lists skip the numbered and lettered bullets. Lettered bullets are offered only when the list has 26 items or fewer. Org also cycles bullets with S-<left> and S-<right> on an item; Orgstar does not bind those on items.

Numbered and lettered lists are renumbered whenever a list command changes them, and by C-c C-c on any item. To start a list at a given number, put a counter after the bullet, as in Org:

5. [@5] fifth
6. sixth

An item with [ ] after its bullet has a checkbox. [X] is checked, and [-] marks a parent item whose children are partly checked.

- [-] packing
  - [X] passport
  - [ ] charger

Toggle Checkbox (C-c C-x C-b) checks or unchecks the item on the caret's line, or every item in the selection. C-c C-c on an item toggles its checkbox too, and on an item without one, repairs the list. A parent item's checkbox follows its children: it can't be checked while children are unchecked ("Cannot toggle this checkbox: unchecked subitems").

Toggle Checkbox works only on item lines. Org's behaviour on a heading, toggling the checkboxes of the region or subtree, is not available.

A cookie [/] or [%] on a heading or an item shows progress:

• On an item, it counts that item's direct child checkboxes.
• On a heading, it counts the checkboxes of the top-level items in the heading's own section. If the section has none, it counts the TODO children: direct child headings with a keyword, and how many of them are in a done state.

* Groceries [1/3]
- [X] milk
- [ ] eggs
- [ ] bread

* Release [50%]
** DONE Tag the build
** TODO Write the notes

Cookies update when you toggle or insert a checkbox, when a child heading's TODO state changes, when you archive an entry, and when you press C-c C-c with the caret on the cookie. A cookie with nothing to count shows [0/0] or [100%]. Tags are realigned when the cookie's width changes.

The COOKIE_DATA property changes what a heading's cookie counts, as in Org:

For TODO statistics, COOKIE_DATA is read with inheritance, from the parent or an ancestor. Orgstar counts TODO children hierarchically, as Org does with org-hierarchical-todo-statistics at its default.

Insert Structure Template (org-insert-structure-template, C-c C-, in the Emacs and Doom presets) asks for a block type, one keystroke:

Press TAB to type any other type. These are Org's default org-structure-template-alist; Orgstar does not read a custom one. The block is inserted at the caret's indentation. With a selection, the block wraps the selected lines, and for src, example, export and comment blocks, lines that would read as headings or keywords are protected with a leading comma. For src and export, the caret ends on the opening line after a space, ready for the language; otherwise it ends inside the block. The case of BEGIN and END follows the case of the type you typed.

Typing < and a key at the start of a line (after blanks only) and then completing expands it as org-tempo does. <s becomes:

#+begin_src
#+end_src

with the caret after begin_src. The keys are those of the table above, plus <L, <H, <A and <i, which insert #+latex:, #+html:, #+ascii: and #+index: keyword lines.

Completion runs with Complete at Point (C-M-i in the Emacs preset, C-SPC in Doom's insert state; in the Mac preset, from the palette). In the Doom preset the completion list also opens by itself after a short pause once you have typed < and a letter, and TAB or RET takes the selected candidate. TAB alone does not expand <s in the Emacs or Mac preset.

TAB on a block's first or last line folds or unfolds it. Blocks are open when a file opens unless org-cycle-hide-block-startup is on in config.toml or the file has #+STARTUP: hideblocks (nohideblocks overrides the setting the other way). See The editor for folding in general.

Edit Block (org-edit-special, C-c ', Mac ⌃⌘') edits a src, example or export block in a separate editor. See Code blocks.

Set Property asks for the key, offering the keys used in the file, Org's standard keys and the properties named in COLUMNS formats; on a property line, Return takes that line's key. It then asks for the value. If the key has allowed values, those are offered and required unless the list includes :ETC; otherwise the values the key has elsewhere in the file are offered. An empty answer keeps the current value. The drawer is created if the entry has none, and lines are aligned as Org's org-property-format ("%-10s %s") aligns them. Setting TODO sets the entry's TODO keyword instead.

Delete Property asks which of the entry's properties to remove, when it has more than one, and removes the drawer if it becomes empty. Delete Property Everywhere removes a key from every entry in the file and reports how many it changed. Property Action, run by C-c C-c in a property drawer, asks s (set), d (delete) or D (delete everywhere).

A property KEY_ALL lists the values KEY may take, separated by spaces, with quotes around values that contain spaces. Orgstar looks for it on the entry, then its ancestors, then the file:

#+PROPERTY: Status_ALL open blocked done

Next and Previous Allowed Value step through the list on a property line. TODO and PRIORITY take their values from the file's keywords and priority range. A property whose value is [ ] or [X] toggles between them.

Orgstar inherits properties as Org does with org-use-property-inheritance at its default of nil: a property applies only to the entry that has it, with these exceptions:

• CATEGORY, ARCHIVE, COLUMNS, LOGGING and the header-args properties are always inherited from ancestors and #+PROPERTY: lines.
• ID and CUSTOM_ID are never inherited.
• KEY_ALL allowed values and COOKIE_DATA for TODO statistics are looked up through the ancestors.

Orgstar has no setting for org-use-property-inheritance.

Org computes some properties instead of reading them from a drawer. Orgstar treats these as special and doesn't offer them as allowed-value lists: ALLTAGS, BLOCKED, CLOCKSUM, CLOCKSUM_T, CLOSED, DEADLINE, FILE, ITEM, PRIORITY, SCHEDULED, TAGS, TIMESTAMP, TIMESTAMP_IA and TODO. Column view computes ITEM, TODO, PRIORITY, TAGS, ALLTAGS, DEADLINE, SCHEDULED, CLOSED and CLOCKSUM; the others show as empty there.

Column View opens a sheet with the entries from the view's top (the entry with the COLUMNS property, or the entry at the caret; the whole file before the first heading). Column View of File shows every entry in the file. Click a row to go to its heading. Done (or Escape) closes the sheet.

The sheet is read-only. Org's column view lets you edit values in place and writes parent summaries back into the file; Orgstar's does neither. Change values with Set Property, or edit the drawer.

View ▸ Show or Hide Columns and Clock opens an inspector beside the editor. Its Columns tab shows the same table for the open file, kept current as you type. Choose File for every entry or Subtree for the entry at the caret. The row of the heading at the caret is shown in bold, and clicking a row goes to it. The Clock tab is described in Dates and clocking.

Insert Column View Table (org-columns-insert-dblock, C-c C-x i) asks what to capture: local (the default, the entry at the caret), global (the whole file) or an ID of an entry. It inserts a columnview dynamic block and fills it:

#+BEGIN: columnview :hlines 1 :id local
| ITEM | TODO | PRIORITY | TAGS |
|------+------+----------+------|
| ...  |      |          |      |
#+END:

C-c C-c (Mac ⌃⌘X) on the #+BEGIN: line, or C-c C-x C-u anywhere in the block, updates it. Updating writes summary values into the parents' properties, as Org does. The block takes these parameters:

Existing #+TBLFM: lines after the table are kept. An :id of the form file:path (another file) is not supported.

Archive Subtree (org-archive-subtree, C-c C-x C-s or C-c $, Mac ⌃⌘A, Doom SPC m A or SPC m s A) moves the subtree at the caret to an archive.

The archive location is read from, in order: the ARCHIVE property of the entry or an ancestor, a #+ARCHIVE: line in the file, and Org's default %s_archive::. A location is file::heading, where %s stands for the current file's name:

Relative paths are relative to the current file's folder, and ~ is your home folder. A new archive file starts with a line Archived entries from file followed by the source's path.

The archived entry gets these properties, as with Org's default org-archive-save-context-info: ARCHIVE_TIME, ARCHIVE_FILE, ARCHIVE_OLPATH, ARCHIVE_CATEGORY, ARCHIVE_TODO and ARCHIVE_ITAGS (empty ones are left out). Within the same file, tags it inherited are added to its heading. After the subtree leaves, the parent's statistics cookies are updated. The entry's TODO state is not changed.

If the archive file is open, the subtree goes into its buffer. Otherwise Orgstar writes the archive file first and removes the subtree from the source only after that succeeds. Org's option org-archive-location in Emacs is not read; use the ARCHIVE property or #+ARCHIVE:. Archiving from the agenda is covered in Agenda.

Toggle ARCHIVE Tag (org-toggle-archive-tag, C-c C-x a, Doom SPC m s a) adds or removes the ARCHIVE tag on the entry at the caret. Adding it folds the subtree.

Subtrees tagged ARCHIVE stay where they are, but are folded when a file opens and in sparse trees, and are left out of column view. TAB opens an archived subtree like any other; Org's org-cycle-open-archived-trees behaviour, which keeps them closed, is not reproduced. See TODOs and tags for tags in general.

Archive to Archive Sibling (org-archive-to-archive-sibling, C-c C-x A) moves the subtree at the caret under a sibling heading named Archive with the ARCHIVE tag, creating it at the end of the parent's children if needed. The moved entry gets an ARCHIVE_TIME property, and the Archive sibling is folded.