The editor

The editor shows an org file as plain text with its markup styled or hidden, folds headings, drawers and blocks the way Org does, and reports position and state in a modeline and echo area below the text.

What the editor shows

The editor holds the file's text exactly as it is on disk. Styling, hidden markup, indentation and images are display only; none of them change the file.

Org files open with the caret at the start of the file, as in Emacs. Buffers you had open when you quit reopen with the caret where you left it.

Markup

View ▸ Show Markup (⇧⌘M; palette: Show or Hide Markup) is off by default. While it is off:

• Link brackets and targets are hidden, so [[https://orgmode.org][Org]] shows as an underlined Org, as with org-link-descriptive.
• Emphasis markers (the * of bold, the = of verbatim and so on) are hidden when org-hide-emphasis-markers is on, which is the default.
• Entities and sub- and superscripts are drawn as characters when org-pretty-entities is on, which is the default (see Entities below).

The line with the caret always shows its markup, so you can edit it. Moving to another line hides it again. Turn Show Markup on to see all markup everywhere. The config.toml setting is show-markup in [orgstar].

The two Org options are in Settings ▸ Editing as "Emacs hides emphasis markers (org-hide-emphasis-markers)" and "Emacs shows entities as characters (org-pretty-entities)", and in config.toml as org-hide-emphasis-markers and org-pretty-entities. They also tell orgstar how wide your Emacs displays text, so tag alignment, table alignment and M-q produce the same file Emacs would. Set them to match your Emacs.

Styling

• Headings are bold and coloured by level (eight colours, as org-level-1 to org-level-8). Levels 1 to 3 are larger than body text: each level is a step larger than the one below it, and level 4 and deeper are body size. The step is Settings ▸ Appearance ▸ "Headings grow by N pt a level" (1 pt by default, 0 to 8).
• TODO and DONE keywords are bold, in the TODO or DONE colour, or a colour you set for that keyword.
• Priorities, tags, timestamps, comments, keywords (#+TITLE: and the like), planning lines and drawers, block delimiters and tables each have a colour; footnotes, targets, macros and LaTeX share one.
• Bold, italic, underline and strike-through are drawn as such; verbatim and code get their own colour and background.
• Links are underlined.
• Blocks (#+BEGIN_… to #+END_…), dynamic blocks and fixed-width lines are drawn on a shaded band across the whole width of the editor, as Emacs extends the org-block face. Code in src blocks is highlighted for its language (see Code blocks).
• A folded heading shows an ellipsis after its line.

Colours come from the theme and follow the system's light or dark appearance. The font, size and line spacing are in Settings ▸ Appearance; colours are set in config.toml. See Configuration. Use a monospaced font: tags and tables line up by columns.

Indentation and stars

Org files display as org-indent-mode shows them, by default: each heading's body is indented to start one column past its stars, all stars but the last are hidden, and a wrapped heading title continues under the title. The indentation is display only; the file keeps its text at the left margin.

Body lines that wrap continue under their own text: past leading spaces, and past a list item's bullet and checkbox, as adaptive-wrap does.

With both off, headings show all their stars and bodies start at the left margin. Both settings are in config.toml only, and are read when a file opens.

Entities

When org-pretty-entities is on and Show Markup is off:

• An entity such as \alpha or \to is drawn as its character (α, →), taking one column.
• x_{1} and x^{2} are drawn lowered and raised, without their markers. Braces are required: x_1 is left as typed.

Entities are left as typed on the caret's line, in comment lines and inside blocks. Sub- and superscripts are left as typed inside emphasis, links and keywords.

Inline images

Org ▸ Show or Hide Inline Images (C-c C-x C-v in the Emacs and Doom presets), as org-toggle-inline-images does, draws images in place of their links. The echo area reports how many images it displayed.

A line shows as an image when it holds nothing but a file: or attachment: link to an image file with no description:

#+ATTR_ORG: :width 400
[[file:images/diagram.png]]

• Recognised extensions: png, jpg, jpeg, gif, svg, webp, tif, tiff, bmp, heic, avif.
• Paths are relative to the file's folder; ~ is expanded. Images at http(s) links show when org-display-remote-inline-images is download or cache; see Remote images.
• attachment: links, such as [[attachment:photo.jpg]], show the file from the entry's attachment folder, found as following the link finds it: the DIR property, else the ID folder under org-attach-id-dir. See Outlines for attachments.
• #+ATTR_ORG: :width N sets the width in points. Images are never wider than the editor.
• The link text is hidden while its image shows, except on the caret's line.

To show images when a file opens, add #+STARTUP: inlineimages to the file, or set org-startup-with-inline-images = true in config.toml. #+STARTUP: noinlineimages turns it off for one file.

LaTeX previews

Show or Hide LaTeX Previews (C-c C-x C-l in the Emacs and Doom presets, and in the command palette) draws LaTeX fragments and environments as typeset math, as org-latex-preview does. The echo area reports how many fragments it previewed.

The area is $\pi r^2$, and \(\sqrt{2}\) is irrational.
\begin{equation}
\int_0^1 x\,dx = \frac{1}{2}
\end{equation}

• $…$ and \(…\) are typeset as inline math, $$…$$, \[…\] and environments as display math. equation, align, gather and their starred forms are typeset as their bodies, aligned or gathered.
• The math is typeset by orgstar itself, with the Latin Modern Math font, in the editor's text color and size; it needs no TeX installation and works on iOS. It reads the math commands LaTeX's amsmath has for formulas, not packages a file loads with #+LATEX_HEADER. A fragment it can't read stays as text.
• The caret's line shows the source, so you can edit it.
• Fragments in source and example blocks aren't previewed.

The command switches previews for the whole buffer; Org's C-u forms, which act on the section at point, aren't there. To preview when a file opens, add #+STARTUP: latexpreview to the file, or set org-startup-with-latex-preview = true in config.toml. #+STARTUP: nolatexpreview turns it off for one file. After switching between light and dark appearance, switch previews off and on to redraw them in the new color.

What isn't rendered

Images in links that have a description, and images on lines with other text, show as links.

Folding

Headings, drawers and blocks fold as in Org. Folding is display only and isn't saved in the file.

Cycling

The titles in the palette and the Org menu are Cycle Visibility, Cycle Global Visibility, Toggle Fold, Open Fold and Close Fold.

Toggle Fold and Open Fold act on a heading line: a folded heading opens one level, showing its body and its child headings, each folded. On an open heading, Toggle Fold folds it and Open Fold does nothing. Close Fold folds the subtree of the heading the caret is under, from anywhere in it.

TAB on a heading line cycles that heading: folded, then its children, then the whole subtree, then folded again. A heading without children goes straight from folded to open. TAB on the first or last line of a drawer or block folds or opens it; drawer and block folds are kept apart from heading folds, so cycling a heading leaves them as they are. Elsewhere TAB does what it otherwise would: in a table it moves to the next field, and in plain text it inserts a tab.

In Doom's insert state, TAB and S-TAB on a heading demote and promote it, and on a list item indent and outdent it, as Doom's +org-indent-maybe-h does. Use normal state to fold.

S-TAB cycles the whole file through three states, starting at the first:

1. Overview: top-level headings only.
2. Contents: every heading, no bodies.
3. Show all: everything, with blocks opened. Drawers stay folded.

Overview and contents also fold drawers before the first heading.

Clicking a heading's stars cycles that heading, as TAB does on it.

The caret can't rest in folded text: moving forward into a fold jumps past it, and moving back into one goes to the end of the heading line. Going to a location from the outline pane, search, a link or the agenda opens whatever folds hide it.

Folding when a file opens

With no #+STARTUP visibility option, a file opens with every heading shown. Drawers start folded (org-cycle-hide-drawer-startup, on by default); blocks start open (org-cycle-hide-block-startup, off by default). Both settings are in config.toml.

#+STARTUP options a file can set:

#+STARTUP: content hideblocks

When the file sets a visibility (overview, content, showall, showNlevels and the like, but not showeverything), orgstar then applies each heading's VISIBILITY property and folds subtrees tagged ARCHIVE, as org-cycle-set-visibility-according-to-property and org-cycle-hide-archived-subtrees do. VISIBILITY takes folded, children, content or all:

* Reference
:PROPERTIES:
:VISIBILITY: folded
:END:

#+STARTUP options are read from the file and from any #+SETUPFILE it names, and take effect when the file opens. To apply changed options to an open file, close its buffer and open it again.

Narrowing to a subtree or block, and sparse trees, also hide text; see Outlines.

Panes and windows

A window can show more than one buffer at once, or one buffer in more than one place, as Emacs windows do. Split Pane Below (C-x 2) and Split Pane Right (C-x 3) divide the pane with the focus in two; the new pane shows the same buffer, and the focus stays where it was. Drag the line between two panes to resize them. Close Pane (C-x 0) removes the focused pane, Close Other Panes (C-x 1) leaves only it, and Next Pane (C-x o) moves the focus through the panes in reading order. With several panes, a bar along the top marks the one with the focus. The sidebar, the outline and the title follow the focused pane. In the Doom preset these are SPC w s, SPC w v, SPC w d, SPC w o and SPC w w, and C-w with the same letters in normal state; the Mac preset and the View menu use ⌃⌘2, ⌃⌘3, ⌃⌘0, ⌃⌘1 and ⌥⌘`.

Each pane has its own caret, selection and scroll position, and its own tabs (see Files and folders): the buffers it has shown. Everything else about a buffer is the buffer's, as in Emacs: its text and undo, its folds, narrowing and sparse tree, its evil state and mark, shrunk table columns and inline images. Two panes on one buffer therefore show the same folds, and a fold made in one shows in the other. Closing a pane leaves its buffers open; closing a buffer (C-x k) takes it out of every pane, which falls back to the buffer it showed before.

New Window (C-x 5 2, ⌥⌘N, File ▸ New Window) opens a window of panes alone, without the sidebar or search, on the buffer the focused pane shows, as a second Emacs frame. Commands act on the pane with the focus whichever window it is in; Quick Open, the palette and search open from the main window and show their result in the focused pane. Closing the window closes its panes and leaves the buffers open.

The modeline

The line under the editor shows, from the left:

Lines count from 1. Columns count from 0, as Emacs's column-number-mode does: a tab advances to the next multiple of 8, and wide characters such as CJK count as two columns. Hover over an item for a description.

The word count follows edits after a pause. The Git branch is read from the repository's HEAD file without running git, and checked again every 5 seconds; worktrees and submodules are followed.

The running clock is covered in Dates and clocking; the evil states in Keys and commands.

The echo area

The line under the modeline is the echo area, as Emacs's minibuffer. It shows:

• Messages from commands, such as Stored: … or Not an org file. A message stays for 4 seconds.
• A pending key prefix. After C-c it shows C-c-. If you pause for about 0.6 seconds, a grid of the keys that can follow appears, each with the command it would run at the caret, or +prefix for a further prefix, as which-key shows them. C-g cancels the prefix and shows Quit. A sequence that isn't bound shows, for example, C-c z is undefined, and does nothing; in the Doom preset this includes sequences after SPC.
• Prompts, when a command asks a question.

Prompts

A prompt shows its question and a text field, which takes the keyboard.

• Type an answer and press Return.
• When the prompt has choices (buffers, refile targets, tags), up to 12 of them list above the field, filtered as you type: characters match in order, and the best match is listed first. Tab completes the field to the first match. Return accepts the first match when the prompt requires one of its choices, and the typed text otherwise. Clicking a choice accepts it.
• Prompts that take several values, such as tags separated by colons, complete only the part after the last separator.
• Escape cancels the prompt; the command reports Quit.

Date prompts also show a date picker, and S-<left>, S-<right>, S-<up> and S-<down> move the date by a day or a week; see Dates and clocking. TODO keywords and tags with fast-selection keys show a key menu instead of a text field; see TODOs and tags.

When a prompt closes, the keyboard goes back to the editor.

Completion

Complete at Point (completion-at-point) completes the word before the caret from what Org knows at that position.

With one candidate, it is inserted. With several, a list opens under the caret, showing up to 16 rows. Nothing is selected until you pick a row.

The list follows what you type and closes when nothing matches. Candidates are those that start with what you typed.

What is completed, by position:

Elsewhere, Complete at Point reports No match. Completion is for org files only.

Electric pairs

Typing an opening bracket inserts its closing partner, as electric-pair-mode does. The pairs are (), [], {}, <> and a pair of double quotes.

• Typing a closing character in front of the same closer moves over it instead of inserting another, skipping whitespace before it.
• DEL between an empty pair deletes both.
• RET between a pair opens a blank line between them.
• With text selected, typing an opening or closing character, or a double quote, wraps the selection.
• No pair is inserted where it would leave the brackets unbalanced (electric-pair-preserve-balance).

Electric pairs are on by default and work in org files only. Set electric-pair-mode = false in config.toml to turn them off. Plain Emacs has them off; Doom pairs with smartparens.

Spell checking

Spell checking is off by default. Turn it on for the current buffer with Check Spelling While Typing from the palette (SPC t s in Doom normal state); the echo area says whether it is now on or off. To have it on in every file, set spell-check = true in config.toml.

Misspelt words are underlined, using the macOS spelling dictionary. In org files, orgstar doesn't mark words where spell-fu skips them: code, verbatim, links, timestamps, tags, TODO keywords, priorities, list bullets, checkboxes, keywords and affiliated keywords, planning and clock lines, property drawers, the first and last lines of drawers and blocks, the whole of src, example, export and comment blocks, LaTeX, entities, macros, targets, footnote references, citations, table formulas and fixed-width lines.

orgstar never corrects spelling on its own; automatic spelling correction, text replacement and smart quotes and dashes are off.

On iOS, spell checking follows spell-check in the synced config.toml, and is off by default.

Wrapping and filling

Long lines wrap at the edge of the editor by default. View ▸ Truncate or Wrap Long Lines (toggle-truncate-lines) switches the current buffer to long lines that run off the right edge, with a horizontal scroll bar, and back. The echo area says which is now in effect.

To truncate lines in every file, turn on Settings ▸ Editing ▸ "Long lines run off the edge instead of wrapping", or set org-startup-truncated = true in config.toml. The default is to wrap, as Doom does; Emacs's own default is to truncate.

Wrapping is display only. To rewrap the text of a paragraph, use Org ▸ Fill Paragraph (org-fill-paragraph), which breaks the paragraph's lines at the fill column: M-q in the Emacs preset and in every Doom state, ⌃⌘P in the Mac preset. With a selection, it fills every paragraph the selection touches. In Doom's normal and visual states, gq and gw with a motion fill the paragraphs in the lines it covers (gqq and gww for the current lines); gq leaves the caret on the last line, gw where it was. Unlike Fill Paragraph, gq and gw keep extra spaces between words and at the ends of lines, as Doom does. See Keys and commands. The fill column is Settings ▸ Editing ▸ "M-q fills to column N" (80 by default, 40 to 200), or fill-column in config.toml.

auto-fill-mode breaks lines as you type: typing a space past the fill column breaks the line at the last space before the column, as often as it takes, and the new line starts with the line's fill prefix, as org-auto-fill-function has it: a list item's text lines up under the item, a comment line starts with #, and headings, tables and code aren't broken. Turn it on for every file with auto-fill-mode = true in config.toml, or for the current buffer with View ▸ Turn Auto Fill On or Off (auto-fill-mode, in the palette too); the echo area says Auto-Fill mode enabled in current buffer or disabled. Only a typed space fills, not RET.

View toggles

Toggles that apply to the current buffer last until it closes; the config.toml setting decides how each file starts. Changing those settings, and org-startup-indented and org-hide-leading-stars, affects files opened afterwards, not buffers already open.

Line numbers

Line numbers show in a margin left of the text, as display-line-numbers-mode shows them: one number per line of the file, so wrapped lines are numbered once and folded lines are skipped. The caret's line number is brighter. Line numbers are on by default.

View ▸ Line Numbers chooses how they count, as display-line-numbers-type does in config.toml:

In the relative and visual kinds the caret's line shows its own number, as display-line-numbers-current-absolute does. display-line-numbers-type = false turns the numbers off. The iOS editor has no line numbers.

Themes

The editor's font, size, line spacing and heading sizes are in Settings ▸ Appearance. Colours for the editor, the sidebar, the modeline, line numbers, the selection and the caret come from config.toml, under [theme] for both appearances, [theme.light] and [theme.dark] for one, and [theme.todo] for colours of TODO keywords. Settings ▸ Appearance ▸ Show Default Theme opens default-theme.toml, which lists every colour with its default value. Changes apply while orgstar runs. See Configuration.

The iOS editor uses the same theme and display settings, read from the synced config.toml; see iPhone and iPad.

Undo

Each buffer has its own undo history, kept while other buffers show.

A command's whole change undoes in one step, separately from the typing around it. Restoring a recovery version and resolving a Syncthing conflict copy can be undone too.

The undo history is cleared when the buffer reloads or merges changes from disk, and when you take the disk version or merge with markers to settle a conflict; see Files, folders and buffers. The Emacs preset has no redo key other than ⇧⌘Z, and undo is linear, not Emacs's undo tree.

Finding text in a file

C-s and C-r in the Emacs preset search as you type (isearch-forward, isearch-backward): the echo area shows I-search: and what you have typed, the next match is selected as each character goes in, and the other matches are highlighted. While searching:

A space matches any run of spaces and tabs, and an upper-case letter makes the search case-sensitive, as Emacs's defaults have it. C-M-s and C-M-r search with a regular expression (isearch-forward-regexp); patterns are ICU regular expressions. Folded text opens around a match. In Doom, / and ? search the same way with a regular expression, the echo area showing / or ? and the pattern; RET ends it as Vim's search does, so n and N repeat it, and Esc or C-g go back. On iOS, C-s and C-r work with a hardware keyboard, and Incremental Search is in Commands; typing on the on-screen keyboard adds to the search. iOS doesn't highlight the other matches.

Edit ▸ Find opens the find bar above the text.

In Doom, :s/PATTERN/REPLACEMENT/ and :%s/…/…/ with the g and i flags substitute with regular expressions on the current line or in the whole file.

To search all your files, use the toolbar's search field; see Files, folders and buffers.

Accessibility

The editor works with VoiceOver. VoiceOver reads the text as it is shown rather than as stored: hidden link brackets and targets, hidden emphasis markers and hidden stars are skipped, entities are read as the characters drawn for them, and narrowed table columns are read as drawn. Folded text is still read, so the whole file is available. Lines, the caret position and the selection are reported in terms of the shown text.

Other parts of the window are labelled: tabs in the tab bar are buttons, with the current one marked selected, and each close button names its buffer and says whether it is unsaved; the modeline's unsaved dot reads "Unsaved changes", and the Doom state tag reads, for example, "Normal state".

The editor keeps the system's keyboard navigation and text editing; the presets only add bindings. See Keys and commands.