docs/manual/guide/02-the-editor.org
332 lines · 28223 bytes
1#+TITLE: The editor
2#+DESCRIPTION: How the editor displays org text, folds it, reports state in the modeline and echo area, completes, checks spelling, pairs brackets, wraps lines and undoes.
3#+LEDE: 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.
4
5* What the editor shows
6
7The 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.
8
9Org 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.
10
11** Markup
12
13View ▸ Show Markup (=⇧⌘M=; palette: Show or Hide Markup) is off by default. While it is off:
14
15- Link brackets and targets are hidden, so =[[https://orgmode.org][Org]]= shows as an underlined =Org=, as with =org-link-descriptive=.
16- Emphasis markers (the =*= of bold, the === of verbatim and so on) are hidden when =org-hide-emphasis-markers= is on, which is the default.
17- Entities and sub- and superscripts are drawn as characters when =org-pretty-entities= is on, which is the default (see /Entities/ below).
18
19The 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]=.
20
21The 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.
22
23** Styling
24
25- 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).
26- TODO and DONE keywords are bold, in the TODO or DONE colour, or a colour you set for that keyword.
27- 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.
28- Bold, italic, underline and strike-through are drawn as such; verbatim and code get their own colour and background.
29- Links are underlined.
30- 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 [[file:11-code-blocks.org][Code blocks]]).
31- A folded heading shows an ellipsis after its line.
32
33Colours 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 [[file:13-configuration.org][Configuration]]. Use a monospaced font: tags and tables line up by columns.
34
35** Indentation and stars
36
37Org 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.
38
39Body lines that wrap continue under their own text: past leading spaces, and past a list item's bullet and checkbox, as =adaptive-wrap= does.
40
41| Setting | Default | What it does |
42|-----------------------------------------+---------+----------------------------------------------------------------------|
43| =org-startup-indented= | on | Indent bodies under their headings. =#+STARTUP: indent= or =noindent= overrides it per file. |
44| =org-hide-leading-stars= | off | Without indentation, show only a heading's last star. =#+STARTUP: hidestars= or =showstars= overrides it. |
45
46With 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.
47
48** Entities
49
50When =org-pretty-entities= is on and Show Markup is off:
51
52- An entity such as =\alpha= or =\to= is drawn as its character (=α=, =→=), taking one column.
53- =x_{1}= and =x^{2}= are drawn lowered and raised, without their markers. Braces are required: =x_1= is left as typed.
54
55Entities 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.
56
57** Inline images
58
59Org ▸ 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.
60
61A line shows as an image when it holds nothing but a link to an image file with no description:
62
63#+BEGIN_SRC org
64#+ATTR_ORG: :width 400
65[[file:images/diagram.png]]
66#+END_SRC
67
68- Recognised extensions: =png=, =jpg=, =jpeg=, =gif=, =svg=, =webp=, =tif=, =tiff=, =bmp=, =heic=, =avif=.
69- Paths are relative to the file's folder; =~= is expanded. Remote URLs are not displayed.
70- =#+ATTR_ORG: :width N= sets the width in points. Images are never wider than the editor.
71- The link text is hidden while its image shows, except on the caret's line.
72
73To 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.
74
75** What isn't rendered
76
77LaTeX 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.
78
79* Folding
80
81Headings, drawers and blocks fold as in Org. Folding is display only and isn't saved in the file.
82
83** Cycling
84
85| Action | Emacs and Mac presets | Doom | Org command |
86|--------------------------------+-----------------------+------------------------------------------------------+----------------------|
87| Cycle the heading or element at the caret | =TAB= | =TAB= in normal and visual state | =org-cycle= |
88| Cycle the whole file | =S-TAB= | =S-TAB=, =z A= in normal state; =S-TAB= in visual state | =org-global-cycle= |
89| Open or fold the heading | | =z a= in normal state | =+org/toggle-fold= |
90| Open the heading one level | | =z o= in normal state | =+org/open-fold= |
91| Fold the subtree the caret is in | | =z c= in normal state | =outline-hide-subtree= |
92
93The titles in the palette and the Org menu are Cycle Visibility, Cycle Global Visibility, Toggle Fold, Open Fold and Close Fold.
94
95Toggle 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.
96
97=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.
98
99In 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.
100
101=S-TAB= cycles the whole file through three states, starting at the first:
102
1031. Overview: top-level headings only.
1042. Contents: every heading, no bodies.
1053. Show all: everything, with blocks opened. Drawers stay folded.
106
107Overview and contents also fold drawers before the first heading.
108
109Clicking a heading's stars cycles that heading, as =TAB= does on it.
110
111The 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.
112
113** Folding when a file opens
114
115With 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=.
116
117=#+STARTUP= options a file can set:
118
119| Option | Effect when the file opens |
120|----------------------------------------+-------------------------------------------------------------|
121| =overview=, =fold= | Top-level headings only |
122| =content= | Every heading, no bodies |
123| =showall=, =nofold= | Everything |
124| =show2levels=, =show3levels=, … | Headings down to that level, no bodies |
125| =showeverything= | Everything, including drawers and blocks; =VISIBILITY= properties are ignored |
126| =hidedrawers=, =nohidedrawers= | Fold or open drawers |
127| =hideblocks=, =nohideblocks= | Fold or open blocks |
128| =indent=, =noindent= | Indent bodies under headings, or not |
129| =hidestars=, =showstars= | Hide all stars but the last, or not |
130| =inlineimages=, =noinlineimages= | Show image links as images, or not |
131| =align=, =noalign= | Align every table, or not (=org-startup-align-all-tables=) |
132| =shrink= | Narrow table columns that have width cookies |
133
134#+BEGIN_SRC org
135#+STARTUP: content hideblocks
136#+END_SRC
137
138When 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=:
139
140#+BEGIN_SRC org
141,* Reference
142:PROPERTIES:
143:VISIBILITY: folded
144:END:
145#+END_SRC
146
147=#+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.
148
149Narrowing to a subtree or block, and sparse trees, also hide text; see [[file:04-outlines.org][Outlines]].
150
151* The modeline
152
153The line under the editor shows, from the left:
154
155| Item | Shown when | What it shows |
156|----------------------------+------------------------------------+-------------------------------------------------------------------|
157| Evil state | Doom preset | =NORMAL=, =INSERT=, =VISUAL=, =V-LINE= or =V-BLOCK=, on a coloured tag |
158| Unsaved dot | the buffer has unsaved edits | a small dot |
159| Outline path | the caret is under a heading | the headings containing the caret, outermost first, as =Projects › House › Roof= |
160| Running clock | a clock is running | elapsed time and the clocked heading; click for Clock Out, Cancel Clock and Go to Clocked Entry |
161| Selection counts | text is selected | lines, words and characters in the selection, as =count-words-region= |
162| Line and column | always | =LINE:COLUMN= of the caret (the end of the selection) |
163| Word count | always | words in the whole file, as =count-words= |
164| Encoding notes | the file differs from UTF-8 with LF | =Read-only=, =BOM= and =CRLF=, in orange |
165| Git branch | the file is in a Git repository | the checked-out branch, or the first 7 characters of the commit when detached |
166
167Lines 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.
168
169The 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.
170
171The running clock is covered in [[file:06-dates-and-clocking.org][Dates and clocking]]; the evil states in [[file:03-keys.org][Keys and commands]].
172
173* The echo area
174
175The line under the modeline is the echo area, as Emacs's minibuffer. It shows:
176
177- *Messages* from commands, such as =Stored: …= or =Not an org file=. A message stays for 4 seconds.
178- *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=.
179- *Prompts*, when a command asks a question.
180
181** Prompts
182
183A prompt shows its question and a text field, which takes the keyboard.
184
185- Type an answer and press =Return=.
186- 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.
187- Prompts that take several values, such as tags separated by colons, complete only the part after the last separator.
188- =Escape= cancels the prompt; the command reports =Quit=.
189
190Date 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 [[file:06-dates-and-clocking.org][Dates and clocking]]. TODO keywords and tags with fast-selection keys show a key menu instead of a text field; see [[file:05-todos-and-tags.org][TODOs and tags]].
191
192When a prompt closes, the keyboard goes back to the editor.
193
194* Completion
195
196Complete at Point (=completion-at-point=) completes the word before the caret from what Org knows at that position.
197
198| Preset | Key |
199|--------+----------------------------------------------------------|
200| Emacs | =C-M-i= |
201| Doom | =C-SPC= or =C-@= in insert state; the list also opens by itself after you type two characters and pause for 0.4 seconds, as Doom's corfu does |
202| Mac | no key; run Complete at Point from the palette, or bind one in =keymap.toml= |
203
204With 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.
205
206| Key | In the list |
207|-----------------------------+----------------------------------------------------------------------------|
208| =C-n=, =<down>=, =C-j= | Next candidate; past the last one the selection goes back to what you typed |
209| =C-p=, =<up>=, =C-k= | Previous candidate |
210| =TAB= | Insert the selected candidate; with none selected, insert the part all candidates share |
211| =RET= | Insert the selected candidate; with none selected, close the list and insert a newline |
212| =ESC= | Close the list; the key then does what it otherwise would |
213| =C-g= | Close the list |
214
215The list follows what you type and closes when nothing matches. Candidates are those that start with what you typed.
216
217What is completed, by position:
218
219| Where | Candidates |
220|----------------------------------------------+----------------------------------------------------------------|
221| =#+= at the start of a line | keyword names (=TITLE=, =STARTUP=, =OPTIONS=, …), in upper and lower case |
222| After =#+STARTUP:= | startup options |
223| After =#+OPTIONS:= | export options |
224| After =#+DATE:= | today's date as a timestamp |
225| After =#+EXCLUDE_TAGS:=, =#+SELECT_TAGS:=, =#+LANGUAGE:=, =#+PRIORITIES:= | the usual values |
226| =<= and a letter at the start of a line | structure templates (=<s= for a src block and so on); see [[file:11-code-blocks.org][Code blocks]] |
227| After =#+BEGIN_SRC= | languages, then header arguments |
228| After =#+BEGIN: clocktable= | clock table options |
229| After =[[= | link types and the file's link abbreviations |
230| After =[[*= | heading titles in the file |
231| After =\= | entity names |
232| After =:= at the end of a heading | tags: those in =#+TAGS=, or else tags used in the file and across your folders |
233| After the stars of an empty heading | TODO keywords |
234| =:= at the start of a line in a property drawer | property names the entry doesn't have yet |
235| =:= at the start of a line elsewhere | drawer names |
236
237Elsewhere, Complete at Point reports =No match=. Completion is for org files only.
238
239* Electric pairs
240
241Typing an opening bracket inserts its closing partner, as =electric-pair-mode= does. The pairs are =()=, =[]=, ={}=, =<>= and a pair of double quotes.
242
243- Typing a closing character in front of the same closer moves over it instead of inserting another, skipping whitespace before it.
244- =DEL= between an empty pair deletes both.
245- =RET= between a pair opens a blank line between them.
246- With text selected, typing an opening or closing character, or a double quote, wraps the selection.
247- No pair is inserted where it would leave the brackets unbalanced (=electric-pair-preserve-balance=).
248
249Electric 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.
250
251* Spell checking
252
253Spell 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=.
254
255Misspelt 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.
256
257Orgstar never corrects spelling on its own; automatic spelling correction, text replacement and smart quotes and dashes are off.
258
259On iOS, spell checking follows =spell-check= in the synced =config.toml=, and is off by default.
260
261* Wrapping and filling
262
263Long 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.
264
265| Preset | Key |
266|--------+------------------------------|
267| Emacs | =C-x x t= |
268| Doom | =SPC t w= in normal state |
269| Mac | menu or palette only |
270
271To 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.
272
273Wrapping 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 [[file:03-keys.org][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=. Orgstar has no auto-fill: lines are not broken as you type.
274
275* View toggles
276
277| Toggle | Menu | Keys | Default | =config.toml= | Scope |
278|-------------------------------+-------------------------------+-------------------------------------------------+---------+----------------------------------+----------------|
279| Show Markup | View ▸ Show Markup | =⇧⌘M= | off | =show-markup= | every buffer |
280| Show Line Numbers | View ▸ Show Line Numbers | =⇧⌘L= | on | =display-line-numbers-type= | every buffer |
281| Inline images | Org ▸ Show or Hide Inline Images | =C-c C-x C-v= (Emacs, Doom) | off | =org-startup-with-inline-images= | current buffer |
282| Spell checking | palette | =SPC t s= (Doom) | off | =spell-check= | current buffer |
283| Truncate long lines | View ▸ Truncate or Wrap Long Lines | =C-x x t= (Emacs), =SPC t w= (Doom) | off | =org-startup-truncated= | current buffer |
284
285Toggles 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.
286
287** Line numbers
288
289Line 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.
290
291* Themes
292
293The 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 [[file:13-configuration.org][Configuration]].
294
295The iOS editor uses the same theme and display settings, read from the synced =config.toml=; see [[file:14-ios.org][iPhone and iPad]].
296
297* Undo
298
299Each buffer has its own undo history, kept while other buffers show.
300
301| Action | Menu | Mac | Emacs preset | Doom (normal state) |
302|--------+-------------+---------+---------------------------+---------------------|
303| Undo | Edit ▸ Undo | =⌘Z= | =⌘Z=, =C-/=, =C-_=, =C-x u= | =u= |
304| Redo | Edit ▸ Redo | =⇧⌘Z= | =⇧⌘Z= | =C-r= |
305
306A 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.
307
308The 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 [[file:01-files-and-folders.org][Files, folders and buffers]]. The Emacs preset has no redo key other than =⇧⌘Z=, and undo is linear, not Emacs's undo tree.
309
310* Finding text in a file
311
312Edit ▸ Find opens the find bar above the text.
313
314| Menu item | Shortcut | Emacs preset | Doom |
315|-----------------------------------+----------+-------------------+-----------------------|
316| Edit ▸ Find ▸ Find… | =⌘F= | =C-s=, =C-r= | =SPC s s= |
317| Edit ▸ Find ▸ Find and Replace… | =⌥⌘F= | =M-%= | |
318| Edit ▸ Find ▸ Find Next | =⌘G= | | |
319| Edit ▸ Find ▸ Find Previous | =⇧⌘G= | | |
320| Edit ▸ Find ▸ Use Selection for Find | =⌘E= | | |
321
322In the Emacs preset =C-s= and =C-r= open the find bar; they are not incremental search. 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.
323
324To search all your files, use the toolbar's search field; see [[file:01-files-and-folders.org][Files, folders and buffers]].
325
326* Accessibility
327
328The 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.
329
330Other 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".
331
332The editor keeps the system's keyboard navigation and text editing; the presets only add bindings. See [[file:03-keys.org][Keys and commands]].