Org mode Basics
EasyOrg is based upon Org mode which is a structured way of writing text files. There is nothing special to an Org mode text file other than that some special keywords and formatting are used and this formatting can be interpreted by EasyOrg and other tools supporting Org mode such as Emacs.
Org mode Basics
Below is a basic overview of the Org mode syntax as well as how this integrates with the features provided by EasyOrg. You can find a more complete documentation of Org mode on the official Org mode site.
Headlines and Text
Headlines in a document start with one or more stars '*'. The number of stars denotes the Headline level.
* Headline level 1
Body text below the headline
** Headline level 2
More body text.
*** Headline level 3
Todo items
A TODO is simply a headline with the keyword 'TODO' after the star(s). You can use more than one star to denote its level within the document.
* TODO This is a todo.
This is body text belonging to the todo. Here you can
write text and note covering multiple lines.
- List item 1
- List item 2
You can also include list items in the TODOs body text.
A TODO can have several states. By default there is TODO and DONE. You can define and add custom states as you like. For example WAIT, CANCELED, PENDING etc.
Nested Todo items
One or more TODOs below a parent TODO will belong to the parent. In the Agenda, when using the 'By Header' view, you will see the sub-todos listede below its corresponding parent todo.
** TODO I'm a parent todo
*** TODO I belong to my parent todo which is on level 2 (**)
I'm on level 3 (***)
*** TODO I'm a child AND parent todo
I'm on level 3 too.
**** TODO Level 4
Tags
A TODO can have one or more tags which is a way to label or categorize the TODO.
* TODO This is a todo with tags. :work:expenses:
Priority
A TODO can have a priority level attached to it. A priority is added between the TODO keyword and the Headline text. By default it's a character 'A', 'B' or 'C' written between square brackets preceded by a hash '#'. 'A' is the highest priority and 'C' the lowest. If no priority is explicitly assign to a TODO then it is considered having priority 'B', i.e. it is in the middle.
* TODO [#A] This todo has the highest priority.
It's possible to assign more levels and also define the default priority level.
Lists
You can create unordered and ordered lists. Just write each list item on its own line with a dash '-' or '+' in front.
- Item 1
- Item 2
- Item 3
For ordered lists start the line with a numeric value followed by a dot '.' or right parenthesis ')'.
1. Item one
2. Item two
3. Item three
Checkboxes
Inside a TODO you can add a list of items with checkboxes. They are useful in cases where a TODO consists of several small steps that you want to keep track of and check off one by one. You create an empty checkbox using brackets with a whitespace in between [ ] and a checked checkbox with an 'X' instead of whitespace: [X]. The list of checkboxes should be in the body of the TODO.
A TODO with checkboxes could look like the following:
* TODO An example with checkboxes in the body text.
In the body we can add a list of small tasks with checkboxes.
- [ ] I need to do this.
- [X] I have done this.
- [ ] And I also need to do this.
Tables
You can write tables with headers and cells like so:
| Name | Phone | Age |
|-------+-------+-----|
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
Source Code Blocks
To write source code and make sure EasyOrg understands it and formats it correctly you add it between a #+BEGIN_SRC and a #+END_SRC. They have to be written on their own lines.
#+BEGIN_SRC
function add(a, b) {
console.log('Testing');
return a + b;
}
#+END_SRC
Scheduling
A TODO can have a deadline date and time and/or a scheduled date and time. Deadline means it should be done by this date and scheduled means the TODO is meant to be worked on at this date and time.
A deadline or schedule is added just below the headline of a TODO as shown in the examples below.
* TODO A todo with a deadline.
DEADLINE: <2020-02-18>
* TODO A todo with a scheduled date.
SCHEDULED: <2020-02-18>
A TODO which has a deadline or is scheduled will show up in the Agenda views based on these dates.
If you have a regular meeting at a certain date and time you should use an Active timestamp as explained in the section below and not a SCHEDULED or DEADLINE keyword.
From the official Org Manual:
Important: Scheduling an item in Org mode should not be understood in the same way that we understand scheduling a meeting. Setting a date for a meeting is just a simple appointment, you should mark this entry with a simple plain timestamp, to get this item shown on the date where it applies. This is a frequent misunderstanding by Org users. In Org mode, scheduling means setting a date when you want to start working on an action item.
Active and passive timestamps
Related to DEADLINE and SCHEDULE are the active and passive timestamps. An active timestamp will cause an entry to be visible in the Agenda and sorted according to its date. Typically active timestamps can be used to define a meeting date. An active timestamp is a timestamp written within angle brackets. Example:
* Meeting about EasyOrg
<2020-02-18 Tue 13:00>
A passive timestamp is a timestamp written within square brackets. They do not make the note/TODO to show up in the agenda. They are used more as a reference and form of documentation. Example:
* Paid back 100 USD to Steve.
[2020-02-18]
Active and passive timestamps can be attached to regular headlines and texts and don't have to be used exclusively with TODOs.
Effort
When you write down TODOs it can often be useful to add the amount of effort you expect it to take. This information can be used in the Agenda to for example easily find TODOs that can quickly be made in case you have some spare time at hand. They can also be used by EasyOrg to estimate the time it will take to complete a set of TODOs within a project or sub-project.
* TODO Fix typos in document on page 5.
:PROPERTIES:
:EFFORT: 0:15
:END:
EasyOrg provides an easy way to add Efforts to your document.
Drawers and Properties Drawers
Drawers is a special construct where you can store data or metadata related to a note or TODO. You can easily hide and show the drawer data in the editor. You already saw an example of a properties drawer in the Effort section above. The PROPERTIES drawer is a special drawer used for storing properties. You are free to give your properties any name you want.
A custom property:
:PROPERTIES:
:COST: 150
:END:
A special LOGBOOK drawer where you can store clocking information:
:LOGBOOK:
CLOCK: [2022-12-01] => 6:30
:END:
A custom drawer:
:MYDRAWER:
Here is some text which I might want to hide and only refer to sometimes.
:END:
Links
Internal Links
Internal links are written like:
[[this-is-an-internal-link][Link name]]
[[internal-link-without-explicit-name]]
To link to another Todo within the same document one can create a link target on this other Todo. By adding the same text within angle brackets '<<>>' as in the link we can link them together, eg. <<this-is-an-internal-link>> would be a link target for the above link. The link target should be unique within the document.
Link to a link target:
[[link-target]]
Link to a CUSTOM_ID target:
[[#20230514-130433]]
Link to a heading target:
[[*First few words of header]]
File Links
Basic link to another file:
[[file:my-file-name.org]]
Relative file path (relative to the current org-file):
[[file:./../my-file-name.org]]
Absolute file path:
[[file:/home/user/william/my-file-name.org]]
Link to a link target within another file:
[[file:my-file-name.org::link-target]]
Link to a CUSTOM_ID target within another file:
[[file:my-file-name.org::#20230514-130433]]
Link to a heading target within another file:
[[file:my-file-name.org::*First few words of header]]
External Links
External links to websites are written like:
[[https://www.example.com/a-page][External Link Name]]
External links to files are written like:
[[/home/john/documents/example.org][My Friendly Name]]
Images
You can embed images by using the same syntax as links.
You can specify an abolute path to the image file:
[[/home/user/my-image.jpg]]
Or use a relative path:
[[./my-image.png]]
Supported image file formats are: jpg/jpeg, png and gif.