orgweb/quickstart.org

Getting started with Org-mode

:PROPERTIES: :CUSTOM_ID: getting-started :END:

In its simplest form, Org is like any other markup language.

You can write Org syntax in any text editor.

However, to experience the full potential of Org you need an editor that transforms Org syntax into a living, interactive document.

Preamble

:PROPERTIES: :CUSTOM_ID: preamble :END:

At the start of a file (before the first headline), it is common to set the title, author and other export options.

,#+title: The glories of Org
,#+author: A. Org Writer

Headlines

:PROPERTIES: :CUSTOM_ID: headlines :END:

Lines that start with an asterisk * are headlines.

A single * denotes a 1st-level headline, ** denotes a 2nd-level headline, etc.

,* Welcome to Org-mode
,** Sub-heading
Each extra ~*~ increases the depth by one level.

In their simplest form headlines are just the start of a section. However, any headline can also become a TODO item.

TODO items are the basic building block that Org uses to track and organize all kinds of tasks.

To add a TODO item to a heading, start the heading with a TODO keyword such as TODO or HOLD.

,* TODO Promulgate Org to the world
,** TODO Create a quickstart guide

Markup

:PROPERTIES: :CUSTOM_ID: markup :END:

To mark up text in Org, simply surround it with one or more marker characters. Bold, italic and underline are fairly intuitive, and the ability to use strikethrough is a plus. You can combine the basic markup in any order, however code and verbatim need to be the *_~inner-most~_* markers if they are present since their contents are interpreted _literally_.

To markup text in Org, simply surround it with one or more marker characters.
*Bold*, /italic/ and _underline_ are fairly intuitive, and the ability to use
+strikethrough+ is a plus.  You can _/*combine*/_ the basic markup in any
order, however ~code~ and =verbatim= need to be the *_~inner-most~_* markers
if they are present since their contents are interpreted =_literally_=.

See Emphasis Markers for more details.

Lists

:PROPERTIES: :CUSTOM_ID: lists :END:

Unordered lists start with +, -, or *~[fn::~* cannot be used to start a plain list if it is immediately preceded by a newline because it will be interpreted as a headline.]. Ordered lists start with 1., 1), A., or A). Ordered and unordered bullets can be nested in any order.

To buy:
1. Milk
2. Eggs
   - Organic
3. Cheese
   + Parmesan
   + Mozzarella

Lists can contain checkboxes [ ], [-], [X].

- [ ] not started
- [-] in progress
- [X] complete

Lists can contain tags (and checkboxes at the same time).

- [ ] fruits :: get apples
- [X] veggies :: get carrots

Links

:PROPERTIES: :CUSTOM_ID: links :END:

To create a link put the target between two square brackets, like so: [[target]]. You can include a description in square brackets after the target [[target][desc]].

The order is easy to remember because it is the same as an html == tag <a href="target">desc</a> and you can't mix up brackets and parentheses because there are only square brackets!

Org supports a wide variety of types of link targets, and you can also add your own. Link types are indicated with a type: prefix, i.e., [type:target]. If no type: is provided, org searches the current file for a headline that matches target.

Some examples:

[[https://orgmode.org][a nice website]]
[[file:~/Pictures/dank-meme.png]]
[[earlier heading][an earlier heading in the document]]

More info

For more on links, see the manual sections for Internal Links and External Links.

Images

:PROPERTIES: :CUSTOM_ID: images :END:

Org mode automatically recognizes and renders image links during export. Just link to an image (don't include a description). That's it. \\ ~https://upload.wikimedia.org/wikipedia/commons/5/5d/Konigsberg_bridges.png~

https://upload.wikimedia.org/wikipedia/commons/5/5d/Konigsberg_bridges.png

Images located on your computer can also be rendered in the Emacs buffer with C-c C-x C-v.

Blocks

:PROPERTIES: :CUSTOM_ID: blocks :END:

Org mode uses #+BEGIN ... #+END blocks for many purposes. Some of the basic blocks types quote, example, and src.

If you all you need is monospace text, you can use an example block.

,#+BEGIN_EXAMPLE
monospace
,#+END_EXAMPLE

However, example blocks do not give you the power of Org babel. For that you need a source block. Source blocks provide syntax highlighting, code execution, literate programming, and more.

,#+BEGIN_SRC emacs-lisp
(message "Hello world")
,#+END_SRC

More info

A hello world example cannot even begin to scratch the surface Org mode's support for working with source code.

Tables

:PROPERTIES: :CUSTOM_ID: tables :END:

Org mode comes with a table editor complete with support cell references and formulas.

In its simplest form a table is text separated using pipes |.

| I    | am  | a    | table |
| with | two | rows | !     |

A more useful example is this comparison of existing Literate programming / reproducible research tools (from Schulte et al. 2012).

| Tool         | Literate programming? | Reproducible Research? | Languages |
|--------------+-----------------------+------------------------+-----------|
| Javadoc      | partial               | no                     | Java      |
| Haskell .lhs | partial               | no                     | Haskell   |
| noweb        | yes                   | no                     | any       |
| Sweave       | partial               | yes                    | R         |
| Org-mode     | yes                   | yes                    | any       |

Worried about aligning free text tables? Org mode does it in a single keystroke -- tab.

Comments

:PROPERTIES: :CUSTOM_ID: comments :END:

Org mode has a variety of ways to add comments.

Line comments start with #. \\ Inline comments wrap @@comment:like so@@. \\ Block comments are wrapped with #+BEGIN_COMMENT and #+END_COMMENT. \\ Section comments can be created by adding the COMMENT keyword to a headline * COMMENT like so~[fn::There are a number of more granular ways to control the exact behavior of headlines, including use of the special tags ~:ARCHIVE: and :noexport:.].

# A line comment

Example of an @@comment:inline@@ comment.

Inline comments are used for end of line comments. @@comment:~#~ won't
work@@ Since # only only works if preceeded by a newline follow by
whitespace.

,#+BEGIN_COMMENT
This is a block comment.
It can span multiple line.
As well as other markup.
,#+BEGIN_SRC elisp
(+ 1 2)
,#+END_SRC
,#+END_COMMENT

,* A top level headline
,** COMMENT This section and subsections are commented out
,*** This headline inherits the =COMMENT= keyword
This text is commented out
,** This headline is not commented
This text will be exported and code blocks will run.

Macros

:PROPERTIES: :CUSTOM_ID: macros :END:

Org has many more advanced features built into its syntax. To give only a single example, let's take a look at macros.

,#+MACRO: attn _*/$1/*_
{{{attn(ATTENTION! This text gets all the markup!)}}}

,#+HTML_HEAD: <style>.red{color:red;}</style>
,#+LATEX_HEADER: \usepackage{xcolor}
,#+MACRO: red @@html:<span class="red">$1</span>@@@@latex:\textcolor{red}{$1}@@
Regular text. {{{red(This text will be red.)}}} More regular text.

Next steps

:PROPERTIES: :CUSTOM_ID: next-steps :END:

Looking for something in particular? The () is a good place to start.

Looking for something between this quickstart and the manual? The () is worth a shot.