docs/manual/guide/14-ios.org

The app has four tabs:

Agenda

the agenda over your folders, with capture.

Folders

the folders of org files you added, and their files.

Settings

where the app's settings come from.

Search

file names and the words of headings.

Files open in a reader first. The Edit button in the reader opens the editor. Both use the same open file, so an edit in the editor shows in the reader when you go back.

Orgstar on iOS works on folders you choose, in iCloud Drive or in another app's storage (for example a folder kept by a Syncthing client).

1. Open the Folders tab and tap Add Folder (the folder icon with a plus).
2. Choose a folder in the picker.

Orgstar keeps access to the folder across launches. Each folder appears as a section listing its .org files by their path inside the folder. Remove Folder at the end of a section removes it from Orgstar; the files stay where they are.

Files that iCloud hasn't downloaded to the device yet appear in grey with a cloud icon. Orgstar asks iCloud to download them and lists them as files once they arrive.

Orgstar sees changes made by iCloud and by apps that use the system's file coordination, and reads every folder again each time you return to the app, since not every sync app reports its changes. An open file takes in changes from disk as described in Working alongside Emacs and other tools.

There is no way to open a single file from the Files app. Add the folder that contains it.

Tap a file in Folders, Search or the agenda to read it.

• Tap a heading to fold or unfold it, as TAB cycles it on the Mac. A chevron marks headings with content.
• The file opens with the visibility its #+STARTUP line asks for, then each heading's VISIBILITY property when #+STARTUP sets a visibility. Drawers and blocks are folded as org-cycle-hide-drawer-startup and org-cycle-hide-block-startup say, or as the file's #+STARTUP says (hidedrawers, nohideblocks and the like).
• Text is styled as in the editor, in the theme's colours, font, size, line spacing and heading sizes, on the theme's background: TODO keywords, priorities, tags, emphasis, code, timestamps, links, and the code in src blocks. Text can be selected and copied.
• The reader follows the editor's display settings (see Themes and display below): Show Markup, hidden emphasis markers, pretty entities, indentation, leading stars, inline images and truncated lines. Tables show at full width, without narrowed columns.
• Tap a link to follow it. Links to headings and files in your folders open in the reader; web links open in the browser.
• The toolbar has Outline (a list of headings to jump to), Export, and Edit.

Tap Edit in the reader. The title shows the buffer name, with • while there are unsaved changes. The tab bar is hidden while you edit.

The editor folds headings, drawers and blocks, styles text with the theme from the configuration folder (see Themes and display below), and runs the same Org commands as the Mac. Autocorrection, smart quotes and smart dashes are off; spell checking follows spell-check in config.toml and is off by default.

The toolbar has:

Conflict

shown while the file and your edits conflict; opens the conflict sheet.

?

Undo

More

Commands, Clock In, Show Markup, Recent Entries, Export, Sync Conflict Copies, and Recovered Versions.

Messages from commands show at the top of the editor for a few seconds; tap one to dismiss it.

The Search tab finds:

Files

up to eight org files whose path matches what you type, ranked as Quick Open ranks them on the Mac.

Headings

headings whose title or text contains your words, including unsaved edits in the open file.

Tap a result to open it in the reader. A heading result opens at that heading.

The Agenda tab shows the agenda over all your folders, with the span and start day from the settings (10 days from 3 days ago by default). Each day lists its entries in rows: the time or a status such as Due today or 3d late on the left, the category and the keyword above the title. Days without entries are hidden, except today. Today's overdue entries are in a group of their own, and a line marks the current time between timed entries. Pull down to refresh.

Views (top left)

the built-in views and those in views.toml, Tags and Properties… (a match such as +work-home or TODO="WAIT"), and Search… (a phrase, or snippets such as +invoice -paid).

The bar at the bottom

Earlier, Filter, Today, Go to Date, the span (Day, Week, Month or the configured span, and Log Mode, which adds closed entries and clocked time) and Later.

Filter

keep or leave out tags and categories of the entries shown, or type a filter as Org's / takes it: +keep and -drop tags or categories, <0:30 for effort, /regexp/. The filter in use shows above the bar.

+ on a day's header

captures an entry scheduled on that day (see Capture).

Tap

an entry to read it, at its heading.

Swipe left

on a TODO entry for Done, which sets the first done keyword of its sequence, or Next State.

Swipe right

for Tomorrow, Next Week (next Monday) or Pick Date, which move the entry's scheduled date, or its deadline on a deadline row.

Touch and hold

an entry for TODO State…, Reschedule, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile…, and Archive….

Commands from the agenda change the file directly when it isn't open, and through the editor when it is. If the heading changed since the agenda was built, nothing runs.

With calendar-events on, the agenda also shows events from the Calendar app; see Settings below.

See The agenda for the rows, the views and matches, and the differences from the Mac.

Tap Capture (the pencil icon) in the Agenda or Folders tab.

1. Choose a template. The first template is selected.
2. Answer the template's questions (%^{…}, %^g, %^t and the like), then tap Continue. A template without questions skips this step.
3. Edit the text. The caret is where %? was.
4. Tap File.

Templates come from capture.toml in the configuration folder (see Settings below). Without one, the two default templates apply. A template with immediate-finish files as soon as its questions are answered, and one with jump-to-captured opens the captured entry. %^g offers the target file's tags as choices.

org-protocol://store-link links add the URL to the stored links that Insert Link… offers, and copy it. org-protocol://capture links opened on the device open the capture sheet with the link's template, URL, title and text. When the link names a template key that capture.toml doesn't have, the sheet starts on the first template and shows No capture template "x" with the key.

Clock in from the editor (More ▸ Clock In, or Clock In in Commands) or from an agenda entry's menu. While a clock runs, a bar above the tab bar shows the entry and the time so far as H:MM, updated every 30 seconds, and a Live Activity shows it on the Lock Screen and in the Dynamic Island (see Widgets and the Live Activity). Tap the bar for:

• Clock Out
• Cancel Clock
• Go to Clocked Entry
• Recent Entries
• Clock Report

Recent Entries, in the bar and in the editor's More menu, lists the recently clocked entries; tap one to clock in to it. It also has Clock In to Recent Entry… and Go to Recent Clocked Entry…, and is disabled until you have clocked in once. Commands has Clock In to Recent Entry…, Clock In to Last Entry, Go to Recent Clocked Entry…, Mark as Default Clock Task and Resolve Open Clocks….

Clock questions open in a sheet: the task selection and the resolution keys as lists to tap, and minutes or a date and time as a field. Cancel answers nothing, as q does. Clocking in with no clock running first asks about open clocks in your folders, from the editor, an agenda entry's Clock In or a capture template with clock-in; Resolve Open Clocks… asks about every open clock. Both work as on the Mac.

The iOS app has no idle detection, so org-clock-idle-time doesn't apply. org-clock-history-length does.

Clock Report shows the time per day and heading for the files you choose. It starts with the files that contain clock lines. Turn on Limit dates to choose a range. The share button sends the report as text.

See Dates and clocking.

With reminders on, Orgstar schedules a notification before each timed agenda entry in the next week, appt-message-warning-time minutes ahead (or the entry's APPT_WARNTIME). Tap a notification to open its entry. Notifications show while the app is open too.

iOS lets an app schedule at most 64 notifications, and Orgstar schedules more only while it runs. It updates them when files or settings change, when you return to the app, and every hour while it is open. The agenda's status line says how far ahead reminders are set ("Reminders are set through …"), or that notifications are off for Orgstar in the system Settings app.

Export (in the reader's toolbar and the editor's More menu) offers HTML and Markdown. Either opens the share sheet with a file named after the org file, which you can send to another app or keep with Save to Files. The export reads the file's setup files and follows its export keywords, as the Mac's HTML and Markdown export does.

PDF, ODT, LaTeX and plain-text export need Emacs and aren't available on iOS. See Export.

C-c C-c on a source block asks whether to run it (yes, no, or always for this block), as on the Mac.

On iOS, only Emacs Lisp blocks run. Orgstar evaluates them with its own Emacs Lisp interpreter, which covers a subset of the language. Other results:

• A block in another language: "language blocks need the Mac to run."
• Emacs Lisp the interpreter doesn't have: "This block uses Emacs Lisp that runs only in Emacs, on the Mac."

Table formulas that Orgstar computes itself work on iOS. A table whose formulas need Emacs reports "This table needs Emacs, which runs on the Mac", with the reason, and isn't changed.

Tangling (C-c C-v t, in Commands) works on iOS and writes the tangled files next to the org file, or where :tangle says.

See Code blocks and Tables.

When a file changes on disk while you have unsaved edits, Orgstar merges the change into your edits. When the changes overlap, the conflict sheet opens. It shows the difference (lines marked - are on disk, + in your version) and offers:

Keep Mine

write your version over the disk version.

Use Disk Version

replace your edits with the disk version.

Merge with Markers

put both versions in the editor, with conflicting lines between <<<<<<< and >>>>>>> markers, to fix and save.

Later

decide later. The Conflict button in the toolbar opens the sheet again. Nothing is saved until you decide.

The version you don't keep goes to the recovery folder.

More ▸ Sync Conflict Copies lists Syncthing's conflict copies of the file (name.sync-conflict-…), each compared with the file, with Keep File, Merge and Use Copy. The copy goes to the recovery folder and is removed. When a file with conflict copies opens in the editor, a message says how many there are.

More ▸ Recovered Versions lists the versions of the file kept in the recovery folder, newest first, each compared with the editor's text. Restore puts a version's text in the editor as an edit you can undo.

See Working alongside Emacs and other tools for how merging and recovery work.

The iOS app reads its settings from a configuration folder: a folder holding config.toml and capture.toml, such as a copy of the Mac's ~/.config/orgstar synced through iCloud Drive or another app.

1. Open the Settings tab.
2. Tap Choose Folder… and choose the folder.

Changes to the files apply as they sync, and again each time you return to the app. Problems in the files show in red under the folder. "No config.toml in folder; the defaults apply" means the folder has no config.toml.

Stop Using This Folder returns every setting to its default.

The Agenda, TODO Dependencies and Calendar sections are the only places the app changes a setting itself:

Show days without entries

turns org-agenda-show-all-dates on or off.

Blocked entries

Dimmed, Hidden or Shown as usual (org-agenda-dim-blocked-tasks).

TODO Dependencies

Not done before TODO children (org-enforce-todo-dependencies) and Not done with unchecked boxes (org-enforce-todo-checkbox-dependencies).

Show Calendar Events

turns on calendar-events, and asks for access to your calendars. iOS asks for full access, as Calendar has no read-only level; Orgstar only reads. While access is missing the section shows Allow Access to Calendars…; if you declined, allow it in the Settings app under Privacy & Security ▸ Calendars.

The calendars

tap one to show or hide its events (calendar-event-calendars). With every calendar checked the setting is empty, so calendars added later show too.

These write config.toml in the configuration folder, as the Mac's Settings window does, so the Mac sees the change too. Without a configuration folder they are kept on the device.

The In use section shows the TODO keywords, the agenda span and start (for example 10 days, starting 3 days before today), the reminder lead time, the capture template keys, the theme (Default, or the theme file's name), and the font with its size. When font names a family that isn't installed on the device, Font shows the system's font with a note, as System monospaced, 13 pt (JetBrains Mono isn't installed).

These settings from config.toml apply on iOS:

• org-todo-keywords, org-list-allow-alphabetical
• org-tags-column, org-insert-heading-respect-content, org-M-RET-may-split-line, fill-column
• org-hide-emphasis-markers and org-pretty-entities, for what hidden markup shows and for how tag and table alignment and filling measure text, as on the Mac
• show-markup, org-startup-indented, org-hide-leading-stars, org-startup-with-inline-images, org-startup-align-all-tables, org-startup-truncated, org-cycle-hide-drawer-startup, org-cycle-hide-block-startup
• [theme] (font, font-size, line-spacing, heading-size-step, theme-file and colours), [theme.light], [theme.dark], [theme.todo], [theme.category]
• org-log-done, org-log-reschedule, org-log-redeadline, org-log-into-drawer
• org-enforce-todo-dependencies, org-enforce-todo-checkbox-dependencies, org-agenda-dim-blocked-tasks
• org-use-speed-commands, with a hardware keyboard
• electric-pair-mode, spell-check
• org-agenda-span, org-agenda-start-day, agenda-include-subfolders, org-agenda-show-all-dates, org-agenda-skip-scheduled-if-done, org-agenda-skip-deadline-if-done, org-agenda-search-view-always-boolean, org-agenda-search-view-force-full-words
• calendar-events, calendar-event-calendars
• reminders, appt-message-warning-time
• org-clock-history-length

capture.toml and views.toml in the folder apply too. Other settings, including keymap, save and org-clock-idle-time, don't apply on iOS. See Configuration.

Orgstar adds the org files in your folders to Spotlight with their title (#+TITLE, else the file name), author, description, tags, headings and text. A file is indexed again when it changes. Tap a Spotlight result to open the file in Orgstar's reader.

Quick Look in the Files app shows org files as the HTML export renders them.

• Running code blocks in languages other than Emacs Lisp, Emacs Lisp beyond Orgstar's interpreter, and tables that need Emacs.
• PDF, ODT, LaTeX and plain-text export.
• The Mac and Doom keymaps, Vim keys, and keymap.toml.
• Idle detection while a clock runs.
• Import from Emacs.
• The board, column view, the backlinks pane, and the buffer list and tab bar.
• The global capture hotkey and the Settings window.
• Explicit saving.

Commands the iOS app can't carry out show a message instead, such as "Not available on iOS yet" or "Command isn't available on iPhone and iPad." Only tables that need Emacs say that Emacs is needed. Commands that only appear on the Mac, such as Refile from the editor, aren't listed in Commands; refile and archive from the agenda instead.