Users' Guide

Introduction

beorg is an iOS app to help you manage your agenda, tasks and notes. It uses a simple plaintext file format compatible with a powerful system called Org mode.

Rather than store all of your tasks and projects in a black box in the cloud, beorg stores your information in files. You can choose how few or many files to use, for example:

You may have heard of Markdown - a simple way of adding formatting to text without the need for complex file formats. The file format is similar, however whereas Markdown is about headings, lists and simple text styles Org mode is designed to help you get organised.

This users’ guide was last updated for beorg 3.14.0.

Getting started

You can install beorg from the App Store to your iPhone or iPad. When you run beorg for the first time you need to choose how to synchronize your org files. iCloud, Dropbox, Box1, a folder from another app or WebDAV can be used. If you are starting from scratch, and use macOS on the desktop, then iCloud is recommended.

With iCloud no further setup is required. If you want to use another sync method you’ll need to make sure you’ve got an org folder ready in which to store your files.

The tab bar

beorg uses a tab bar to provide access to the main sections of the app. You can quickly switch between the tabs Agenda, Tasks, Files and Settings.

The Agenda

The agenda is the screen shown when beorg starts. It shows the tasks for each day in the current week. Each task in the agenda is an item in one of your org files that has a scheduled date, deadline or active date.

img

You can perform the following actions on a task:

img

img

At the bottom right is a button to show the Quick Capture dialog.

Also at the bottom are buttons to allow you to change the week shown.

To filter your agenda with a search term tap the Search button (top left) or drag down from the top of that week.

Tasks

The Tasks tab lists each org file and the items in that file. By default it shows tasks (that is an item with a state such as TODO), including ones without dates. A summary is shown of the number of tasks and how many are overdue.

img

The same actions on each item that are available on the Agenda tab are available on the Tasks tab.

At the bottom of the Tasks tab is a toggle between showing all incomplete tasks or choosing from a filter. If you’ve activated the Saved Searches extension then any saved searches will also appear in the filter list.

Files

Files is split into two sections. At the top are your pinned files. Next are all the files in beorg.

img

Long press a file to get access to the following options:

You can add a new file by tapping the add button on the navigation bar at the top of the screen.

img

Settings

The Settings tab allows you to setup beorg.

img

The most important section allows you to configure syncing your org files. You can sync files using either iCloud, Dropbox or WebDAV.

Tasks in beorg can notify you to remind you to get them completed. Tasks with a date but no time will generate a notification at the same time everyday. Change “All day tasks start at” to the time you would like these notifications. Tasks with a time will generate there notification a certain number of minutes before the time set. Set “Timed task reminders” to how many minutes before the set time you would like these to fire.

beorg can show events from your calendars alongside your Org mode tasks. In Settings you can choose which calendars are included in beorg. This is useful if you have duplicates, such as multiple holiday calendars.

By default there are two states for tasks - TODO and DONE. It can be helpful to have more states. For example a task which isn’t yet completed could be:

Similarly completed tasks may need different completion statuses. For example:

Sync

beorg can sync files with either iCloud, Dropbox, Box, a folder from another app or WebDAV (this includes services such as NextCloud). Once sync is setup then beorg will sync your files when:

For all other sync methods when:

As beorg works with files it is possible that a file edited in beorg is not the latest version. beorg keeps track of previous versions of files. If a remote change overwrites a local change then you’ll be alerted to this. You can then browse the saved versions and either revert or copy out the overwritten change. Where possible make sure that you don’t have unsaved files on your computer that you are going to edit in beorg.

If using a sync method other than iCloud it can be slow to edit multiple items in quick succession if beorg has to perform a sync after each change. If you find this is the case for you then try disabling ~Auto sync on modify~.

Viewing and editing outlines

You can view and edit files as outlines in beorg. To show a file either swipe an agenda or todo item, or select the file itself from the files tab.

What is an outline?

A file is shown as an outline. An outline is an organised hierarchy of text. You may sometimes see items in an outline referred to as nodes. An item can contain other items, known as it’s children. A headline can also contain text. Here is an example of what beorg writes when you save a file you’ve been working on:

* Headline 1
** Headline 1.1
Some text belonging to headline 1.1
** Headline 1.2
* Headline 2

Folding

beorg allows you to fold (that is show/hide it’s children) an item in the outline. To show/hide the children of an item tap on the left hand side of the screen on the headline. You can see if an item has it’s children hidden because it will contain a triangle pointing right. If it’s children are shown then the triangle will point down. An item with no children will show as an empty circle.

Editing tools

As well as viewing files you can also edit files as well. To edit an existing item tap on the right side of the screen on the headline. So you can see which item is being edited a blue line will appear on it’s left.

img

You can add a new item to the bottom of the document by tapping the Add Item button.

img

The top set of icons in the edit area are as follows:

  1. Hide the editor
  2. Promote an item (that is make it a higher level heading)
  3. Demote an item (that is make an item a child of the item above)
  4. Move an item up
  5. Move an item down
  6. Add an item below the current selection
  7. Add an item above the current selection
  8. Delete the item

You should experiment with these tools before using on an important file.

Below these tools is a switch between editing the item’s headline and editing the text underneath the headline (sometimes referred to as notes).

When editing an item’s headline there are some additional buttons and information which appears:

  1. The state of the item. An item can be marked as TODO, DONE or a custom state you’ve configured in settings. If an item is in a done state then the box shown will contain a tick.
  2. Priority. An items priority is a letter between A and G. An item with a priority of A will appear higher up the list of items in the agenda than one with a priority of D. An item with no priority will appear below those items with a priority.
  3. Tags. You can add or remove tags from that item. Tags are useful when searching lots of items or using saved searches.
  4. Scheduled date/time.
  5. Deadline.
  6. Show on (or when this item should appear in the agenda but won’t then be shown as overdue if that date passes).
  7. Show all item details full screen.

img

Exporting an outline

You can view a file as formatted text by tapping the button at the top right of the screen. If you want to view just part of an outline as text long press the item and choose Export from the popup menu. The formatted view of the document or subtree can be exported as a PDF for printing or sharing via an app.

img

Copy/paste

The beorg outliner supports copy and paste. Long press on an item in the outline to show the menu.

img

When you copy an item it copies the item and any children as a single plain text snippet. You can paste this text into other apps or into a different place in the outline.

When pasting you can choose to:

If beorg does not recognise what is on the clipboard as being in Org mode format then it will ask if you want to paste as a single item or as a list. For example if you had the following in the clipboard…

Line 1
Line 2
Line 3

…and pasted that text as a single item then the item would be given the headline/title “Line 1” and the notes would be set to…

Line 2
Line 3

If however you selected to paste as a list then beorg would add three separate items into the outline:

beorg will also intelligently recognize if you try pasting OPML content. OPML is an XML file format used by most outliners. If you copy some OPML contents to the clipboard and paste into beorg the structure of the pasted content will be retained. This is useful if importing content from apps such as MindNode.

Editing an individual item

Whilst you can edit an item from the file its in, often it is more convenient to edit the item itself directly from the agenda.

The edit screen contains the details about the item and its text (or notes).

img

Dates

An item can be assigned zero or more dates. A date can be:

It is often useful to set both a scheduled and deadline date for an item which is a multi-day project.

In addition to an item being assigned a specific day it can also be given a time.

The date/time editor allows you to quickly set a date to today or tomorrow, and to move forward/backwards in increments of 1 or 7 days at a time. At the top of the date dialog you can see how many days in the past/future the date is and which day (e.g. Monday) it is.

img

To add or remove a time to a date tap the clock icon at the top of the dialog. To remove a date (e.g. you’ve decided not to have a scheduled date now, just a deadline) tap the trash can icon.

img

There are times when its useful to have an item which automatically repeats. beorg supports repeating an item after a certain number of days, weeks, months or years. Here are some examples of repeated tasks:

When a repeated task is marked as done beorg will change the date to when it should next be completed. You can tell beorg to update the date in one of the following ways:

To set a date to repeat:

  1. Tap the Repeat… button at the bottom of the date dialog.
  2. Choose how often you want it to repeat. The first column allows you to choose a number (1, 2, 3, …) and the second whether this is in days, weeks, months or years.
  3. Select how the date should be updated when the task has been completed.

img

Quick capture

You can quickly add items to your quick capture file in one of two ways:

img

Templates

You can create two templates for free. If you need more than two templates then you will need to purchase the Templates extension in-app purchase.

What are templates?

You may find yourself wanting to speed up adding certain types of items in beorg - daily reviews, keeping a journal, adding tasks for completion tomorrow.

beorg gives you the ability to create templates. A template defines one or more of the following:

This will become clearer with an example. Let’s say you want to review your day. An item containing a daily review may need the following:

Managing templates

img

To add a new template:

  1. Swipe up on the + button which appears on the Agenda, TODO and Files tab
  2. Tap Manage Templates
  3. Tap the + button, top right, to start creating your template

img

If you want to delete a template then swipe from right to left on the template and select Delete.

To reorder templates hold down your finger on a template until you have picked it up and then drag to the desired position.

Basic details

A template needs a descriptive name - for example “Journal Entry” or “Daily Review”.

If you don’t specify a file to save to then the current quick capture file will be used.

You can optionally specify a default state and priority to assign to a new item using the template.

Specifying dates

Dates (scheduled, deadline and show on) use a simple syntax to define a date relative to the current date and time.

As a minimum a number of days from today needs to be provided - with 0 being today (as today + 0 days is just today). You can also provide a unit - h (hours), d (days), w (weeks), m (months) and y (years). For example setting scheduled to “1d” or “1” (as the d for day is implicit if no unit is provided) will schedule the item for tomorrow.

Following the number of days (or hours, weeks, months or years) is optionally a “t” signifying that the time should be included. If you are setting a relative number of hours then the “t” is implied. For example “2dt” is two days from today at the time the new item is created, so if today was 23rd January at 09:30 then “2dt” would be 25th January at 09:30.

If you’ve specified “t” so that a time is included then you can also set an absolute time. For example “1dt1300” is tomorrow at 1pm (13:00 in 24-hour time).

A toolbar above the keyboard has common scenarios clearly labelled so the majority of the time the syntax doesn’t need to be manually typed.

Tags

You can specify any number of tags which will be applied to the new item. Each tag must be listed separately. There is no need for the tag to have been previously used.

Headline and notes

The headline and notes can make use of macros. Macros are used primarily to insert the current date and/or time in a format of your choosing. For example “%year% %monthshort% %day%” would insert “2019 Mar 06” if it was currently the 6th March 2019.

The following macros are available:

Macro Description Example output
%today% Date, without time, in Org format 2019-03-23
%now% Date, with time, in Org format 2019-03-23 13:21
%year% Current 4 digit year 2019
%month% Current 2 digit month 03
%monthshort% Current short month name Mar
%monthlong% Current month name March
%day% Current 2 digit day in month 23
%dayshort% Current short day name Wed
%daylong% Current day name Wednesday
%hour% Current hour (24-hour) 13
%minute% Current minute 30

If you find that the above macros are not sufficient then you can call Scheme functions. Some examples of macros making use of Scheme functions:

Example macro Description Example output
%(date-week-day (current-date))% Number of day in week 3
%(date->string (current-date) "~y")% 2 digit year 19

If “Edit Notes Immediately” is checked then when you create a new item using the template you’ll be shown the notes editor automatically. This is useful if you are unlikely to want to edit the pre-filled headline/title.

Subtree

All beorg files are outlines - that is you can nest items inside each other to whatever level you find useful. For example a journal might have the following structure:

* 2019
  * January
     * 2019-01-05 Saturday
       Journal entry contents...
     * 2019-01-07 Monday
       Journal entry contents...
  * February
    * 2019-02-07 Thursday
      Journal entry contents...

At the top level is the year, then nested under the year is each month which has journal entries and then come the journal entries organised by month.

By adding items to the “Subtree” section in the template editor you can tell beorg where you want a new item to be added. You can use the same macros described above if you want to file items by date. Please note that items are always added at the end - which is usually what you want. If beorg doesn’t match the elements in a subtree they will be created.

Search

You can use Search from either the agenda, in which case it is limited to the current week being displayed, or from the TODO tab. Type some words to search for, or a phrase (in double quotes, e.g. “sales meetings”). To narrow down your search even more there is a simple syntax.

img

Syntax overview

Example Description
f inbox Only search in the file inbox.org. You can specify multiple files, for example f file1 f file2 f file3
s todo Must have the state TODO. You can specify multiple states, for example s todo s waiting
t shopping Must contain the tag “Shopping”. You can specify multiples tags, for example t shopping t food
p a Must be of priority #A. You can specify multiple priorities, for example p a p b
d 7 Any date assigned to an item must be within 7 days of today
o A task is overdue
n iphone The notes must contain the text iphone
r author dickens The property author must be equal to dickens (case insensitive on both property name and value)
k Must be an incomplete task (e.g. in a TODO state)

For more advanced use you can write your search in Scheme.

Search basics

Search allows you to filter your agenda or search for specific items on the TODO tab. You can enter text and it will be used to match items which have that text in their headlines. For example entering…

day

…would match items with the headlines “Sunday tasks” and “Day 3” but not the headline “Christmas shopping”.

You enter multiple search terms, all of which must be matched for an item to be shown. For example…

one two

…would match items “One and two verse songs” and “Three two one counting practice”.

If you want to match a phrase then surround it in double quotes. For example…

"one two"

…would match “One two three” but not “two one”.

More advanced searches

Some single characters have special meanings in searches. A list of these is at the top of this help. You can use these to narrow down your search to a particular file, tasks with a certain state, tasks which have certain tags, priorities and dates that are within a certain number of days time.

Here is an example which searches items that have the state WAITING and the tags “callback” and “important”…

s waiting t callback t important

Here is another example which just shows items from the files family, exercise and cooking…

f family f exercise f cooking

Saved searches

If you have a TODO tab search used frequently then you can save that search and then access in the future from the bottom toolbar. Make sure the keyboard isn’t visible, by tapping the Done button on the keyboard, and then a bookmark button will appear in the search bar. Tap this and then tap the + button in the top right. You will then be prompted to provide a name for your search. To remove a search swipe from right to left on a search and tap Delete.

Saved searches is available as an in-app purchase for a small one off costs from the beorg extension manager. Your saved searches will be synced across your devices using iCloud.

img

Searches using Scheme

If a search starts with ( and ends with ) then it will be interpreted as a Scheme expression that should return true or false. The expression will have access to the variable item representing the item being checked.

For example…

(string=? (item-headline item) "Meeting")

…will match any items with the headline Meeting.

There are some helper functions defined in library.org to easily lookup information from an item:

Scheme function Description
item-file the name of the file which the Org task is contained in (e.g. inbox.org)
item-headline the headline of the item (i.e. the task title)
item-state e.g. TODO, DONE
item-priority the priority of the item
item-tags any tags assigned to the item
item-scheduled the scheduled date for the item. If there is no scheduled date then this will be #f (false).
item-deadline the deadline date for the item. If there is no deadline date then this will be #f (false).
item-active-date the active/show on date for the item. If there is no active date then this will be #f (false).
item-overdue #t (true) if the item is overdue
item-properties a list of association lists of properties in this item’s property drawer
item-property provide the property name to get back the string value

You should note that whilst non-Scheme searches are case insensitive you’ll need to handle that yourself - string-upcase and string-downcase will prove useful.

URL Scheme

If you use apps such as Shortcuts or Drafts then you may find the beorg URL scheme useful. The URL scheme allows you to launch the beorg app and do one of the following:

beorg supports x-success and x-cancel arguments, however they are not mandatory.

Adding a new item

To add a new item you need to use the URL beorg://x-callback-url/capture. Without any arguments the quick capture dialog will be shown. You can also supply the following arguments:

Parameter Description Example
title The item headline Shopping List
notes Notes to add to the item Buy eggs
scheduled Schedule the item using a date in the format yyyy-MM-dd 2018-09-18
deadline Set the item deadline using a date in the format yyyy-MM-dd 2018-09-18
file The name of the file, without an extension, to add the item to journal
template Name of a template to apply Daily Review
edit Whether or not the user can edit the item before it is created true

For example beorg://x-callback-url/capture?title=New%20task&notes=Buy%20eggs&scheduled=2017-10-03&file=shopping

If a template is supplied then only the URL scheme parameters title, notes and file are taken into account.

Show the agenda

To view the agenda use the URL beorg://x-callback-url/agenda.

Show the tasks tab

To view the tasks tab use the URL beorg://x-callback-url/tasks.

If you would like to view the results of a search then provide the argument search with the value being the search string, using the same syntax you would use in the UI. For example:

beorg://x-callback-url/tasks?search=t%20bookmark

In the above example the search t bookmark has URL encoded the space so that the parameter becomes t%20bookmark.

View a file

To view a file use the URL beorg://x-callback-url/file with the argument file - e.g. beorg://x-callback-url/file?file=shopping

Search for items

To search for items in beorg there is the URL beorg://x-callback-url/search?search=<SEARCH STRING>. The search string is the same as can be entered into the search control on the Agenda and TODO tabs. You will need to ensure that this is URL encoded.

The URL supplied in the x-success argument will be called with the additional parameter json. This will contain a dictionary with the attributes count (the number of search results) and items (the search results). Each search result is as follows:

Attribute Description Example
title The headline of an item Buy eggs
notes Any accompanying notes Get 6 large free range eggs
state TODO state DONE
priority The item priority (if available) B
tags A list of any tags assigned to item Shopping,Groceries
scheduled The scheduled date/time in ISO-8601 format 2020-01-15T09:00:00Z
deadline The deadline date/time in ISO-8601 format 2020-01-15T09:00:00Z
date The show on/active (i.e. not scheduled or deadline) date/time in ISO-8601 format 2020-01-15T09:00:00Z

The search callback is most useful with the Shortcuts app as part of a larger workflow, and is only available in 2.12.0 and above.

Scripting and advanced customisation

beorg includes a Scheme interpreter which provides an environment for advanced customization and extension of beorg.

For more details see An Introduction to beorg Scripting.

Keyboard shortcuts

beorg comes with extensive support for keyboard shortcuts. For more information see,

beorg Keyboard Shortcuts Reference

Editing files on your computer

beorg writes files using the Org mode syntax. Whilst you can edit these files using any text editor a text editor which understands Org mode will work best. Org mode was written for the Emacs editor - and if you want to use all of the (many) features supported by Org mode then you will want to use Emacs. However there are plugins for other editors including Atom, Visual Studio Code, ViM, Sublime Text and others. These will only support a small fraction of what Org mode is capable of - however beorg only supports a small fraction of the power of the Emacs Org mode anyway!

Limitations

Org mode is a very rich, capable system. If something supported by Org mode isn’t described in this user guide (or can be set in Scheme) then it is likely not currently supported by beorg.

Useful resources

To find out more about Org mode - https://orgmode.org/


  1. Box sync is available via an in-app purchase. ↩︎

Download now for iPhone and iPad

Follow us on Mastodon

Privacy Policy | Press Kit