docs/manual/guide/02-the-editor.org

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.

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

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.

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.

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 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. Remote URLs are not displayed.
• #+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 fragments and environments are coloured but not rendered as formulas. Images in links that have a description, and images on lines with other text, show as links.

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.

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.

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.

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.