Outlines and structure

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.

Every command in this chapter is in the Org menu and the command palette (⇧⌘P), under the title given in the tables, whatever keymap you use. The Org menu shows the keys that run each command in your current keymap.

Keys are listed for the three presets. The Emacs and Doom presets use Emacs notation (M-RET is Meta-Return, C-c C-w is Control-c then Control-w). The Mac preset uses macOS symbols. The Doom preset has every Emacs-preset key that starts with C-c or C-x, and the M-, S- arrow and RET chords, in normal, insert and visual state, plus the Doom keys listed. Where the Mac column says "menu", the Mac preset has no key for the command; run it from the Org menu or the palette, or bind one in keymap.toml (see Keys).

Headings

A heading is a line that starts with one or more stars and a space. The number of stars is its level. A heading and everything under it, down to the next heading at the same or a higher level, is a subtree.

* Project
Notes about the project.
** TODO Write the plan
** Meetings
*** Kickoff

Inserting headings

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

Promoting and demoting

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.

Moving subtrees

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 elements (paragraphs, blocks, drawers, keywords) they drag the element past the one before or after it in the same section, drawer or greater block, as org-drag-element-backward and org-drag-element-forward do. The blank lines between the two stay where they were.

Moving between headings

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.

Toggling headings, items and comments

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.

Selecting a subtree

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.

Subtrees as text

Cut, copy and paste

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.

Cloning with a time shift

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.

Sorting

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.

Narrowing

Narrowing hides everything outside the current subtree or block, so the editor shows only that part of the file. Narrow to Block works on src, example, export, comment and verse blocks (with the blank lines after them) and, for other blocks, on the lines between the opening and closing lines. Edits inside the narrowed text move its bounds as you type. Jumping to a position outside it, from a link, search or the outline pane, widens first.

Narrowing is a view. Commands still see the whole file: for example, a new footnote's definition still goes into the Footnotes section at the end of the file, and a sparse tree searches the whole file.

Sparse trees

Sparse Tree… (org-sparse-tree, C-c /, Doom SPC m s s) folds the file to an overview and then shows only the matches and the headings above them. It asks what to match, one keystroke:

The regular expression uses Emacs syntax. The match syntax for m is the one the agenda's tags search uses (see Agenda). Dates are read as Org reads them (see Dates and clocking).

For a text match, the whole entry around each match is shown; for heading matches, the heading line. The matched text is highlighted, and the echo area reports the number of matches. Subtrees tagged ARCHIVE stay folded. The highlights go away at the next edit or with C-c C-c. TAB and S-TAB work as usual afterwards; cycling leaves the sparse view.

Plain lists

orgstar's list commands are ports of org-list.el. A list item starts with a bullet: -, +, * (not at the left margin, where it would be a heading), or a number followed by . or ). With alphabetical lists on, a., A., a) and A) are bullets too. A description item has :: after its term:

- milk
- eggs
  1. free range
  2. brown
- orgstar :: an org editor for macOS and iOS

List commands

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.

Bullets and numbering

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. S-<right> and S-<left> on an item (Doom C-S-l and C-S-h) cycle forward and backward.

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

Checkboxes and statistics

Checkboxes

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.

Radio lists

A list with :radio in its #+ATTR_ORG: line, other than :radio nil, is a radio list: checking one item unchecks the others. Toggle Checkbox and C-c C-c on an item check it and uncheck the rest of its list (org-toggle-radio-button); items without a checkbox get one.

#+ATTR_ORG: :radio t
- [ ] tea
- [X] coffee
- [ ] water

C-c C-c on an #+ATTR_ORG: or other affiliated keyword line of a list repairs the list, as on an item without a checkbox. Org's org-list-checkbox-radio-mode, which makes every list in a buffer a radio list, isn't available.

Statistics cookies

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.

Blocks

Blocks are lines between #+BEGIN_name and #+END_name:

#+BEGIN_QUOTE
Text to quote.
#+END_QUOTE

Structure templates

Insert Structure Template (org-insert-structure-template, C-c C-, in the Emacs and Doom presets) asks for a block type by key. Org's default keys are:

Press TAB to type any other type. [org-structure-template-alist] in config.toml adds templates or changes these (see Configuration). As in Org, keys of two letters take two keystrokes: when several keys start with the same letter, that letter opens a second choice, where TAB picks the one-letter key, so with el for src emacs-lisp, e TAB inserts an example block and e l the Emacs Lisp block. 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.

org-tempo templates

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 structure templates above, Org's and any in config.toml, 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.

Folding and editing blocks

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.

Drawers

A drawer is a named group of lines between :NAME: and :END:. orgstar writes the PROPERTIES drawer for properties and, depending on org-log-into-drawer, a LOGBOOK drawer for state notes and clock lines (see TODOs and tags and Dates and clocking). You can write any other drawer by hand:

* Meeting
:NOTES:
Private notes, folded away.
:END:

TAB on a drawer's first or last line folds or unfolds it. Drawers are folded when a file opens, as with Org's org-cycle-hide-drawer-startup (true by default in config.toml). #+STARTUP: nohidedrawers keeps them open in one file, and #+STARTUP: hidedrawers folds them when the setting is off.

Insert Drawer (org-insert-drawer, C-c C-x d) asks for a name. With no selection it inserts an empty drawer on a new line; with a selection it puts the selected lines in the drawer. A selection containing a heading is refused.

Properties

Properties are key-value pairs in an entry's PROPERTIES drawer, right after the heading and its planning line:

* Laptop
:PROPERTIES:
:VENDOR:   Apple
:Effort:   1:00
:END:

File-wide properties come from #+PROPERTY: lines and from a PROPERTIES drawer before the first heading. A key written KEY+ appends its value to the inherited one with a space between.

Setting and deleting

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).

Allowed values

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.

Inheritance

orgstar inherits properties as Org does with org-use-property-inheritance, set in config.toml: nil (the default), t for all properties, or property names separated by spaces, such as "STYLE TEAM". An inherited property comes from the nearest ancestor that has it, or from a #+PROPERTY: line. At 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.

The setting applies to property lookups, agenda matches and habits (STYLE), as Org's selective inheritance does.

Special properties

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

Column view shows entries as rows and properties as columns. The columns come from a COLUMNS format, found in this order:

1. a COLUMNS property on the entry at the caret or one of its ancestors (the nearest one wins, and that entry becomes the top of the view);
2. a #+COLUMNS: line in the file;
3. Org's default, %25ITEM %TODO %3PRIORITY %TAGS.

#+COLUMNS: %40ITEM %TODO %Effort(Estimate){:} %CLOCKSUM

Each column is %[width]PROPERTY[(title)][{summary}], as in Org. The width limits the column, the title replaces the property name in the header, and the summary is computed for parent entries from their children. The summary operators are +, $, min, max, mean, X, X/, X%, :, :min, :max, :mean, est+, @min, @max and @mean. The age operators take an active timestamp, as its age now, or a duration, and show the youngest, oldest or mean age in days, hours and minutes (3d 2h 15min); any other value stops the view with "Invalid age". The numeric operators take a format after a semicolon, as in {+;%.1f}.

Subtrees tagged ARCHIVE and commented subtrees are left out.

The column view sheet

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. Done (or Escape) closes the sheet.

Click a cell to select it; the arrow keys move the selection. Go to Entry shows the selected entry's heading in the editor.

Editing goes through the commands Org uses: ITEM changes the headline, keeping its keyword, priority and tags (org-edit-headline); TODO sets the keyword, with logging and state notes (a note is asked for at the bottom of the sheet); PRIORITY, TAGS (tags separated by spaces or colons), SCHEDULED and DEADLINE set those, an empty value removing them; other columns set the property in the entry's drawer, under the column's name in upper case, as Org writes it. CLOCKSUM, ALLTAGS, CLOSED and the other computed columns can't be edited.

The allowed values are the property's _ALL values from the entry, an ancestor or a #+PROPERTY: line, the TODO keywords (and none) for TODO, the priorities for PRIORITY, and [ ] and [X] for a column with an X summary. Without allowed values, n and p say so. On SCHEDULED and DEADLINE they move the date a day later or earlier; Org 9.8.7 signals an error there instead. After each change the sheet captures the view again, so summaries follow. Parent summaries are not written into the file.

On iOS, choose Column View or Column View of File from the editor's More menu. The view scrolls both ways; tap a cell to select it. The bar at the bottom has Edit, which asks for the value with the allowed values listed, Previous Value and Next Value (p and n), and Go to Entry. Done closes it.

The Columns inspector

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.

Column view tables

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. A file: path counts from this file's folder. An ID is looked for in this file, then in the agenda files, as org-id-find does. For another file the table is built from the file on disk, and the summaries are not written into it; Org writes them into that file's buffer.

Footnotes

Footnote Action depends on where the caret is:

• On a reference such as [fn:1], it goes to the definition. If there is none, it asks whether to create one.
• On a definition's label, it goes back to a reference.
• Elsewhere, where a footnote is allowed, it inserts a new reference with the next free number and creates its definition.
• Where a footnote can't go, it shows the footnote menu.

C-c C-c on a reference or a definition's label does the same jumps. After a jump to a definition, the echo area says how to get back: Edit definition and go back with `C-c C-c' or `C-c C-x f' on its label.

New definitions go in a level 1 heading named Footnotes at the end of the file, which is created when needed (Org's org-footnote-section):

* Notes
orgstar reads org files.[fn:1]

* Footnotes

[fn:1] And writes them.

The footnote menu asks, one keystroke:

A reference with no definition gets the text DEFINITION NOT FOUND. when sorted or normalized.

Refiling

Refile… (org-refile, C-c C-w, Mac ⌃⌘W, Doom SPC m r r or SPC m s r) moves the subtree at the caret under another heading, in this file or another one.

It asks for the target with completion. By default the targets are every org file in your folders and every heading down to level 3 in those files, written as the file's path relative to its folder followed by the outline path:

projects.org
projects.org/Work
projects.org/Work/Website
notes/inbox.org/Someday

Choosing a heading makes the subtree its last child, at one level below it. Choosing a file adds the subtree at the end of that file as a level 1 heading. Levels inside the subtree are shifted to match, and tags are realigned. A subtree can't be refiled into itself.

For the open file, targets come from the buffer, including unsaved edits. When the target is another file, orgstar writes that file first, into its open buffer if it has one, otherwise through the normal save path, and removes the subtree from the source only after that succeeds. If the target file changed on disk in the meantime, nothing is refiled.

Three settings in config.toml change the targets, as in Org (see Configuration):

• org-refile-targets, written as Lisp: a list of (FILES . SPEC). FILES is nil (the file you refile from), org-agenda-files, a file name, or a list of file names (relative to the current file's folder). SPEC is (:maxlevel . N), (:level . N), (:tag . "TAG"), (:todo . "KEYWORD"), (:regexp . "RE") or t for every heading; (nil :maxlevel . 3) is read the same way. The tag, keyword and regexp tests look at heading lines, case-sensitively.

  org-refile-targets = "((nil :maxlevel . 3) (org-agenda-files :tag . \"project\"))"

  Empty (the default) is the list above: every file, to level 3.

• org-refile-use-outline-path: how targets are written. file (the default) is the file then the outline path; t the outline path alone; nil the heading alone; full-file-path the file's full path then the outline path; title the file's #+TITLE (or its name) then the outline path; buffer-name as file. With nil, t and buffer-name, targets in other files end with the file's name in parentheses, and files are targets only with file, full-file-path, title and buffer-name. A / in a heading is written \/.
• org-refile-allow-creating-parent-nodes: with t, typing TARGET/New heading, where TARGET is one of the targets, adds New heading at the end of TARGET one level below it (or at the end of the file for a file) and refiles there; confirm asks first. On iOS the Refile sheet offers the new heading when the search field holds such a path.

Otherwise this matches Org with org-reverse-note-order nil (new entries go last), org-log-refile nil and org-refile-keep nil. Refiling from the agenda is covered in Agenda.

Copy to Refile Target… (org-copy, C-c M-w) asks the same way and copies the subtree there, leaving it in place. Go to Refile Target… (C-u C-c C-w, Doom SPC u SPC m r r) asks the same way and jumps to the heading, or to the end of a file.

Archiving

Archive Subtree

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-archive-location in config.toml (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. Archiving from the agenda is covered in Agenda.

The ARCHIVE tag

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 sibling

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.

Attachments

An entry's attachments are files in a folder that belongs to it, as with org-attach. The folder is the entry's DIR property when it has one, relative to the file's folder unless absolute. Otherwise it comes from the entry's ID: data/ab/cdef… for the ID abcdef…, under the org file's folder. The first attachment gives an entry without either an ID property, and it gets the ATTACH tag. attachment: links open files in the folder (see Links).

The Doom keys are under SPC m a; see Keys. Attaching a file stores an attachment: link to it, for Insert Link (C-c C-l). Deleting removes files for good, without the Trash.

On iOS the commands are under More ▸ Attachments, with Attach Photo or Video… for the photo library. Moving and linking aren't offered there. Files, photos and videos shared to orgstar from another app are attached too: the share sheet offers Attach, and orgstar asks for the entry when it next opens.

Encrypted entries

orgstar reads and writes entries encrypted by org-crypt with a passphrase (org-crypt-key nil, symmetric encryption). The text after the entry's planning line, property drawer and logbook, through the end of its subtree, is replaced by an OpenPGP message under the heading:

* Secret :crypt:
-----BEGIN PGP MESSAGE-----

ww0ECQMI…
-----END PGP MESSAGE-----

The commands have no keys, as in Org; run them from the command palette, or bind them in keymap.toml. On iOS they are under More ▸ Encryption.

Remember in the Keychain stores the passphrase for the file. The next command on that file uses it after Touch ID, Face ID or the device password, without asking. org-crypt-tag-matcher in config.toml sets the tag; it must be a single tag, not a match expression.

Messages are written with AES-256 and an iterated and salted SHA-256 key, which GnuPG and Emacs read. Messages using AES-128, AES-192 or AES-256 are read, compressed or not. Messages encrypted to a public key, other ciphers, and AEAD (OpenPGP version 5 and 6) packets are not supported. Saving doesn't encrypt tagged entries, as org-crypt-use-before-save-magic does in Emacs; run Encrypt Tagged Entries….

The outline pane

The outline pane, to the left of the editor, lists the headings of the open org file, indented by level. Click a heading to go to it; folded text around it opens. A heading with no title is shown as (untitled).

Show or hide it with the toolbar button or View ▸ Show or Hide Outline. orgstar remembers the choice for org files; for other files the pane starts hidden and shows "Only org files have an outline." Drag the divider to resize it. While the search field has text, the pane shows search results instead. The backlinks pane, when shown, sits below the outline (see Links).

C-c C-c

C-c C-c (org-ctrl-c-ctrl-c) does what fits the caret's position. In the Emacs and Doom presets it is C-c C-c; in the Mac preset it is ⌃⌘X. In order, it:

Elsewhere it reports that it can do nothing useful.

In the Doom preset, RET in normal state runs Doom's +org/dwim-at-point instead. It follows a link, recalculates a table with formulas or aligns one without, runs a src block, toggles an item's checkbox, or on a heading switches between the first TODO and first done keyword of its sequence.

Speed keys

With org-use-speed-commands set to true in config.toml, single keys run commands when the caret is at the very start of a heading line, before the stars. These are Org's org-speed-commands; the structure ones are:

The full list is in Keys.

Not supported

These Org structure features are not in orgstar:

• Editing values in column view, and writing summaries from it; the columnview dynamic block does write summaries.
• The ORDERED property in the list commands.