Sebastian KaiserA personal engineering notebook

The notebook Writing with Org-mode

Org-mode publishing showcase

I write in Emacs Org-mode. This page is where I check what happens to that writing on its way to the web: Org source is exported by ox-hugo to Markdown, then parsed and rendered by Berlin.

It is both a public example and a publishing fixture. The deliberately deep headings, task states, tables, and code blocks give me a varied document to inspect when I change the pipeline. This is not a claim of complete Org-mode support; it is a place to make the current behavior visible.

What to look for

  • Structure: nested headings and lists should remain understandable outside Emacs, including where the exporter turns deep outlines into lists.
  • Inline content: emphasis, verbatim text, and links should preserve their meaning and remain readable.
  • Tables and tasks: compare the table layout, checkboxes, task labels, tags, and priority markers in the examples below.
  • Code and stored results: source blocks should be readable as listings. Publishing does not execute them; any displayed results are already present in the Org source.

Folding, agenda views, capture commands, and keyboard shortcuts belong to the Emacs authoring experience. Describing them here does not make them interactive features of this static page. Some export-specific material, such as LaTeX, may need additional handling rather than appearing exactly as it does in Emacs.

The examples below were retained from an introductory document described as the example file for a Denver Emacs Org-mode talk. They remain useful as a varied publishing fixture; the talk-oriented examples are not a description of my personal setup.

For these publishing features in a regular article, see Processing JSON with Rust. That link also exercises the resolution of an Org ID into a published page.

This is an example headline

Text can be put into the headline. You can create another headline at the same level with another * character

Another headline

Nesting headlines is as easy as adding another star.

Nested headline

Another nested headline

Deeper

Another headline

  • Deeper...

    • Deeper.....

Basic markup

You can really go as deep as you want. This is the general building block for org-mode navigation.

Next, let's talk about some markup

  • underscores let you underline things
  • stars add emphasis
  • slashes are italics
  • pluses are strikethrough
  • equal signs are verbatim text
  • tildes can also be used

You can generate lists with the - character (seen above), or create numbered ones:

  1. Number one thing
  2. Number two thing
  3. Number three

Showing and hiding headlines

You can hide the contents of a headline by putting the point (cursor) or it and hitting TAB.

You can also toggle hiding and showing of all headlines with SHIFT-TAB.

Tables

Auto expanding tables are one of the coolest features of org-mode, because tables in Markdown just plain suck. In order to create a new table, you can start typing it manually, or press C-c |, which will prompt for the table's dimensions.

First Name Last Name Years using Emacs
Lee Hinman 5
Mike Hunsinger 2
Daniel Glauser 4
Really-long-first-name-guy long-last-name-pers 1

Org-mode links

:PROPERTIES:...

In an org-mode file, you can press C-c l to store a pointer to wherever you are in the file. Then, with (or without) text highlighted hit C-C C-l to make it into a link. The example file for Magit If you don't want to store a pointer (ie, link to a website or something), you can just hit C-c C-l and type or paste the link. To manually create a link, do something like:

The Denver Emacs Meetup Group

Writequit site

Google's web site Google

(ignore the *_SRC blocks for now, we'll get there)

fundamentalLink
[[http://google.com/][Google]]

You can link to files, images, websites, emails, irc, and all kinds of things.

Various things you can add in headers

One of the most common uses for org-mode is a sort of "task list" or TODO list. Org-mode supports this by allowing markers in the headline for the state of a task. Let's look at an example:

TODO This is a task that needs doing

TODO Another todo task

  • sub task one
  • sub task two
  • sub task three

Learn about org-mode

TODO learn todos

TODO learn other stuff

You can toggle each task in a list with the C-c C-c keyboard shortcut.

DONE I've already finished this one

You can change the status of a task by hitting C-c t in the body of a task anywhere, which will prompt for the state to put it in.

You can create as many of these as you'd like, for example (from my own config, use what works best for you, configuring them is a little out of scope right here) here's what I use:

TODO something that needs doing

DONE something that's already done

INPROGRESS something I'm currently doing

WAITING waiting for someone else before doing anything

NEEDSREVIEW there's a PR for this, it needs someone to look at it

HOLD this is in permanent hold until further notice

CANCELLED I don't need this any more

SOMEDAY I'd like to do this someday in the waaaaay off future

A lot of people just use "TODO" and "DONE" though.

Adding tags and priorities

You can add tags by putting them surrounded in ":" in the headline. Additionally, priorities

Headline with a tag org

Another tagged headline turingdenver

Headline with multiple tags orgemacs

Tags are just another way of organizing things.

Important task

Medium task

Non-important task

Again you can configure these, or just use the 3 built in ones.

TODO [1/3] Task with sub headlines

  • TODO Finish thing
  • TODO Finish that other thing
  • DONE Done with a thing

[33%] Task with sub headlines (percent cookie)

  • TODO Finish thing
  • TODO Finish that other thing
  • DONE Done with a thing

The TODO-planner payoff

:PROPERTIES:... So TODOs are all well and good, but what is a really neat feature is when you can easily capture new TODOs and display them easily.

In order to do this, let's configure a couple of Emacs options in your emacs init:

emacs-lispLink
(require 'org)
;; Setup C-c c to capture new TODOs
(global-set-key (kbd "C-c c") 'org-capture)
;; Setup a key bind for the agenda
(global-set-key (kbd "C-c a") 'org-agenda)
;; Set up agenda to know about our file, you can use a list of files or
;; directories here
(setq org-agenda-files '("~/todo.org"))
;; A new template
(setq org-capture-templates
      '(("t" "Todo" entry (file "~/todo.org")
         "* TODO %?\n%U\n")))

Now, hit C-c c to bring up the capture template list, then t to capture a new TODO item.

Once you've captured a few TODOs, you can try out the agenda by hitting C-c a, which will prompt for what agenda you'd like to see, for now hit t to see the TODO list agenda.

Exporting an org-mode buffer

Org has a lot of export options, they are all contained behind a C-c C-e export backend, exporting to HTML, markdown, plain text, pdf, etc.

Further authoring features and source blocks

Org-mode also supports the following authoring workflows. They are listed for context, not as features implemented by this website:

  • refiling (org-refile)
  • source code blocks
  • org-babel
  • clocking in/out
  • table formulas
  • custom agenda views
  • capturing notes (not just TODOs)
  • publishing projects remotely via TRAMP

The remaining examples exercise export of LaTeX, Emacs Lisp and shell source blocks, and stored results. They are display examples, not instructions to run the shell commands below.

a+ba + b

emacs-lispLink
(defun my/function ()
  "docstring"
  (interactive)
  (progn
    (+ 1 1)
    (message "Hi")))
shLink
echo $data > /tmp/foo
for i in `cat /tmp/foo`; do
  echo $i
done
shLink
echo "hi"
shLink
# do some things
echo "stuff"
echo "more stuff"
echo <<hi>>

To enter and edit a block of text, use C-c C-'