Org-mode Basics

Text in org is structured by headings, denoted by lines starting with one or more * so we are currently in a section!

Hopefully you can see straight away that the simple structure provided by org-mode gives a nice way to keep an electronic note book.

Often it is nice to include tables in our notes. Org handles this by using | to separate columns, and a line of — (inserted with C-c -) to add horizontal lines.

Exercise: start typing in this table below; type the first line in verbatim

1. when you get to the "s" of comments, press TAB to go to the next line
2. go up to the previous line and use C-c - to add the row of dashes
3. next enter a few lines of data, using TAB to go through the cells - you should notice the columns changing width as needed

Now, you can move rows and columns around using M-arrow and insert or delete rows and columns using M-S-arrow. Try this out now.

Org mode supports links to files, URLs, and to other points in the org file. In this example let's use an image from my website. First copy it to the current directory. You can do this within emacs but for now just run this command in your terminal.

curl http://www.star.bris.ac.uk/bjm/superman_cluster.png -o superman_cluster.png

To add a link to a file use C-u C-c C-l and type the name of a file. Use tab-completion to select the image we just copied and you will then be asked for a description - you can press enter to leave this blank. This will create a link that looks like this

If you do this in your org file, you won't see the [[ ]] above, instead you'll see the text as a clickable link.

Since the file we have linked to is an image, we can tell emacs to the image in the document using C-c C-x C-v and use the same command to turn the image off again.

You can also click the link with the mouse, or use C-c C-o to follow it, which might open your web browser, an image viewer or open a file in emacs depending on the target of the link.

The structure of a link in org mode looks like this

[[link address][description]]

(I've enclosed the link in an example block which prevents org-mode from trying to interpret as a real link, for the purpose of showing its structure - we'll come back to blocks like this later.)

The link address is the URL or file name, and the description is the text that is displayed, so we can replace our superman link with something tidier like this.

Links to web pages are easy - just put the http address in as the link address. Use C-c C-l as a quick way to add such a link (remember we used C-u C-c C-l for adding a link to a file).

Links to other parts of the org file are added easily like this link. Because the address part of the link matches a headline in this document, then org-mode points the link to that part of the file. Clicking it will move the cursor there.

Finally, we can add a caption and a label to our image like this

which means we can refer to our image later with a link like this one 2

One strength of org-mode is the ability to export to multiple formats. Probably the most useful to begin with are web pages and pdf (via latex) but more are available; to quote the org manual

ASCII export produces a readable and simple version of an Org file for printing and sharing notes. HTML export allows you to easily publish notes on the web, or to build full-fledged websites. LaTeX export lets you use Org mode and its structured editing functions to create arbitrarily complex LaTeX files for any kind of document. OpenDocument Text (ODT) export allows seamless collaboration across organizational boundaries. Markdown export lets you seamlessly collaborate with other developers. Finally, iCal export can extract entries with deadlines or appointments to produce a file in the iCalendar format.

To export your org file to a web page, type C-c C-e to start the exporter and then press h to select html and o to select open. A new web page should now open in your browser.

Similarly, typing l and o in the exporter will convert the org file to latex and then compile it to produce a pdf and display that. Try both of these.

It is possible to add many customisations to the export process. For example, go to the top of the buffer (using M-<) and use C-c C-e and then # to insert an export template. You can then choose to add html or latex (or other) templates (press TAB to see the list).

As an example, add the following to the top of your org file to tweak the appearance of the exported documents.

#+LaTeX_CLASS: bjmarticle
#+TITLE:     Org-mode Basics
#+AUTHOR: Ben Maughan
#+OPTIONS: html-link-use-abs-url:nil html-postamble:auto
#+OPTIONS: html-preamble:t html-scripts:t html-style:t
#+OPTIONS: html5-fancy:nil tex:t
#+HTML_DOCTYPE: xhtml-strict
#+HTML_CONTAINER: div
#+DESCRIPTION:
#+KEYWORDS:
#+HTML_LINK_HOME:
#+HTML_LINK_UP:
#+HTML_MATHJAX:
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.star.bris.ac.uk/bjm/css/bjm.css" />
#+HTML_HEAD_EXTRA:
#+SUBTITLE:
#+INFOJS_OPT:
#+CREATOR: <a href="http://www.gnu.org/software/emacs/">Emacs</a> 24.4.1 (<a href="http://orgmode.org">Org</a> mode 8.3.2)
#+LATEX_HEADER:

This is the default html export template with a couple of tweaks.

• I have added a link to a style sheet to style the html
• I have added a latex class bjmarticle to control the appearance of the generated pdf

The latex class is defined in my emacs config file with the following

(add-to-list 'org-latex-classes
             '("bjmarticle"
               "\\documentclass{article}
\\usepackage[utf8]{inputenc}
\\usepackage[T1]{fontenc}
\\usepackage{graphicx}
\\usepackage{longtable}
\\usepackage{hyperref}
\\usepackage{natbib}
\\usepackage{amssymb}
\\usepackage{amsmath}
\\usepackage{geometry}
\\geometry{a4paper,left=2.5cm,top=2cm,right=2.5cm,bottom=2cm,marginparsep=7pt, marginparwidth=.6in}"
               ("\\section{%s}" . "\\section*{%s}")
               ("\\subsection{%s}" . "\\subsection*{%s}")
               ("\\subsubsection{%s}" . "\\subsubsection*{%s}")
               ("\\paragraph{%s}" . "\\paragraph*{%s}")
               ("\\subparagraph{%s}" . "\\subparagraph*{%s}")))

You'll need some experience of LaTeX to make significant changes here, but the sky is the limit.