Org-mode basics IV: formatting text and source code

This is a continuation of my series of introductory posts on org-mode that are focussed on simple text-based notes. We looked already at structuring your notes and adding tables and links and images to your notes. In this post we will look at formatting the text in your notes.

For today we will look at the effect of formatting on the plain text view of your notes, but very soon we will come to exporting your notes to html and pdf and we’ll see that the formatting is applied to the exported documents very nicely.

We will also look at including executable code in your notes. Hopefully you can see that by putting all these pieces together you can build a very powerful document of your research containing your data, notes, relevant links, source code and results.

As before I suggest adding the notes below to your growing org file. For technical reasons I have to display the notes as plain text below but if you paste them into your org file you’ll see them nicely formatted and coloured like this:

* Formatting text
** Simple formatting
You can apply simple formatting to your text by enclosing words in
special characters. These include
 - /italicised text/
 - *bold text*
 - _underlines_
 - =literal text=
 - ~code~ (generally appears the same as literal text)

Here are the full notes:

* Formatting text
** Simple formatting
You can apply simple formatting to your text by enclosing words in
special characters. These include
 - /italicised text/
 - *bold text*
 - _underlines_
 - =literal text=
 - ~code~ (generally appears the same as literal text)

** Formatted blocks of text
For longer pieces of text you can enclose the text in blocks marking
it as a specific sort of text. I commonly use these ones

#+BEGIN_EXAMPLE
This is an example block into which you can type text that you don't want org to mess with like a [[link]]. This will typically be rendered in a monospace font when exported.
#+END_EXAMPLE

#+BEGIN_QUOTE
This block encloses text that you want to appear as a quotation.
#+END_QUOTE

#+BEGIN_CENTER
This text will be centred when it is exported.
#+END_CENTER

You can save time typing out the block wrapper by using shortcuts. Go
to the start of a new line and type <e and press TAB and it will
expand to an example block. The same works for <q for quote and <c for
centre.

** LaTeX
Org-mode does a good job of understanding snippets of LaTeX (a
[[https://www.latex-project.org/][powerful typesetting language]] used in scientific and other technical
documents). For example, it will correctly export simple superscripts
x^2 or subscripts x_0 or symbols like \alpha, \beta, \gamma.

Org also understands more complex LaTeX like this

\begin{eqnarray}
x^2 + \left(\frac{y}{z}\right)^4 = 0
\end{eqnarray}

but for longer bits of LaTeX it is better to use a LaTeX block. You
start one with <l and TAB

#+BEGIN_LaTeX
LaTeX code goes here
#+END_LaTeX

** Source code blocks
It is also handy to include source code in your notes - on a new line
type <s and TAB to create a source block. You can tell org what type
of code is contained - in this case we'll put in some simple shell
code, so well put "sh" at the top of the block.

#+BEGIN_SRC sh
  echo "Hello $USER! Today is `date`"
  exit
#+END_SRC

You can get org to syntax highlight the text in the block by adding
the following to your [[http://pragmaticemacs.com/emacs/editing-your-emacs-config-file/][emacs config file]] (without the source block
wrapper of course).

#+BEGIN_SRC elisp
;;syntax highlight code blocks
(setq org-src-fontify-natively t)
#+END_SRC

What is more, when the cursor is inside a SRC block, you can use C-c '
to create a new temporary buffer in the major mode of the programming
language you have specified. Type some code in, and then type C-c '
again to come back to this buffer.

** Executing source code blocks
Org-mode can execute your source code blocks and add the output to
your file. This part of org-mode is called babel. I'll write more
about this later, but it is too cool not to mention here.

For example, take the simple code block we had above:

#+BEGIN_SRC sh
  echo "Hello $USER! Today is `date`"
  exit
#+END_SRC

Put the cursor inside the block and hit C-c C-c to execute it. You
will be asked to confirm and then you should see the output appear
like this:

#+RESULTS:
#+begin_example
Hello bjm! Today is Fri 25 Sep 2015 15:03:12 BST
#+end_example

You can do much more with this, like reading input data from a table
in the same file, creating images that appear in the file, extracting
(tangling) all the code snippets into one or more files to be executed
separately, and much more. [[http://orgmode.org/worg/org-contrib/babel/intro.html][Here are some nice examples]].

You can tell org-mode which programming languages to support by adding
something like the following to your [[http://pragmaticemacs.com/emacs/editing-your-emacs-config-file/][emacs config file]]:

#+BEGIN_SRC elisp
;; Some initial languages we want org-babel to support
(org-babel-do-load-languages
 'org-babel-load-languages
 '(
   (sh . t)
   (python . t)
   (R . t)
   (ditaa . t)
   (perl . t)
   (gnuplot t)
   ))
#+END_SRC
  • Kudos to you, thank you for posting this series.

  • Marc Sherry

    What are the “<l" tab-completion snippets called? I'm trying to find a list of supported ones, but it's hard to search for "<l" on google, and `describe-key` on TAB isn't giving me much that's useful.

  • Marc Sherry

    What are the “<l” tab-completion snippets called? I’m trying to find a list of supported ones, but it’s hard to search for “<l” on google, and `describe-key` on TAB isn’t giving me much that’s useful.

    • Phil

      C-h v org-structure-template-alist RET

  • Phil

    I’m really appreciating this series. I’ve been wanting to learn org-mode for years, but the (apparent) time investment needed to get from the basics to doing more complex things had always put me off, so all this time later I’m no better off. These posts are easy bite-sized ways to do what I’ve been failing to do for all this time; so thank you — this really is exactly what I needed.

  • Phil

    I was receiving an error when attempting to execute the source block: org-babel-execute-src-block: No org-babel-execute function for sh! (this from org 8.2.10 in emacs 24.5).

    Loading the library ob-sh resolved that (for the other newbies to all this, the org-babel support libraries all use the ob- prefix). I found it strange that org didn’t automatically know to load that library in that situation, so I’m curious as to whether it’s something which newer (non-default) versions handle automatically, or if you have some org config which is taking care of this?

  • Pingback: Org Basics IV | Irreal()

  • egh

    Unfortunately, wrapping LaTeX math in `#+BEGIN_LaTeX` seems to prevent exporting it properly to HTML. It might be better to encourage the use of `begin … end` and math delimiters `$` or `( …)`.

    • You are right – if I wrap the eqnarray above in a latex block it does not export correctly to html. I had not come across this problem before – thanks for pointing it out!

      I wonder if it is a bug or a feature…

      • egh

        According to the manual it is intended. “It is also possible to create blocks containing raw code targeted at a specific back-end (e.g., `#+BEGIN_LATEX’).” Since it is “raw code” for a back-end it should be LaTeX-specific. “Embedded LaTeX” however is not export back-end specific. Confusing!