Documentation about Org Mode

Unicorn

Emacs org-mode is immensely powerful. I use it primarily to write documentation, especially for software and hardware development.

While learning org-mode, I wrote below lines to capture items I felt were most relevant for me, like on a cheat sheet. This might be useful to other people who have similar requirements.

There is additional content here about how to

generate HTML from org-mode
generate LaTeX documents from org-mode using the LaTeX tool
generate Beamer PDF slides from org-mode using the LaTeX tool
generate PowerPoint slides from org-mode using the pandoc tool

To Outline the Document

Headings

One or more asterisks (stars) plus a space.

Indent/Out-Dent

M-← or M-→

Whole sub-tree:

M-S-← or M-S-→

Change the bullet or enumeration type or style

S-← or S-→

This only works, when the cursor is located on the bullet character. If this is 1. or 1) then the cursor may be at the numeral or at the . or ).

For headings this will toggle to TODO or DONE. Only headings can be TODO items.

Move a whole tree up or down

M-↑ or M-↓

Aligning Text

The usual Emacs M-q (which is fill-paragraph) only works correctly, when a bullet or enumeration is already properly indented.

Insert a Date

C-c ! inserts a date (more precisely: an "inactive date", that does not make it into the agenda)

On the other hand, C-c . inserts an "active date".

Insert Links

I often need to insert relative links. This can be achieved by customizing the variable org-link-file-path-type, i.e. you can put in init.el

'(org-link-file-path-type (quote relative))

Then C-u C-c C-l brings up the mini-buffer, where you can specify a relative path, e.g. by starting with ../ or ./ and using tab-completion to navigate the file system. Note that the out-right "Insert Link" command C-c C-l does not offer tab-completion.

As link anchors, I settled for assigning my own ids to Org mode headings as follows:

* Heading
:PROPERTIES:
:CUSTOM_ID: myanchor
:END:

The Org mode exporter will generate

<h1 id="myanchor">Heading</h1>

from it. Another org mode file could then link to this file using syntax like

[[./mypath/file.html#myanchor][here]]

which Org mode's HTML exporter will convert to

<a href="./mypath/file.html#myanchor">here</a>

Hard Line Break in a Table Cell

In an org-mode table cell, you can force a line break by writing

line1 @<br/> line2

but that will work only in HTML export.

Inserting Literal Text

Either using a ":" (colon) followed by a blank:

: Literal text

or using the following syntax

#+BEGIN_EXAMPLE -i
Literal text
#+END_EXAMPLE

The -i switch preserves indentation.

View

Hierarchy

TAB to fold/unfold

S-TAB to fold/unfold the whole hierarchy

Images

To toggle between viewing the images and viewing the links:

C-c C-x C-v (also works with CUA mode, as long as nothing is selected)

M-x org-toggle-inline-images

Export Tricks

To achieve an image as a clickable html link do

#+MACRO: imglnk @@html:<a href="$1"><img src="$2"/></a>@@

{{{imglnk(./Out.pdf,./Out-Sch_316x217.gif)}}}

Downside: the image does not show in Emacs.

Caveats

org-mode hogs keyboard shortcuts. E.g. C-TAB ‑ which I want to use to switch buffers ‑ I need to re-assign deliberately in my init.el.

My org-mode Settings (via Emacs Customize)

Compatibility with CUA-Mode

To have org-mode work with CUA-Mode, I set org‑replace‑disputed‑keys to TRUE (found this in the org-mode FAQ under "15.10.2 Packages that conflict with Org mode")

To use "Shift-Select" (which I use often) org‑support‑shift‑select has to be set.

How Long Lines Show

I set org-startup-truncated to nil ("off"), to have long lines shown rather than only see an arrow at the end of a long line. However, this spoils the view of wide tables.

Alternatively, you could use the minor mode visual-line-mode, which wraps long lines at word boundaries, at the window border. I.e. if you change the window width, e.g. by changing the frame width, the wrapping will change accordingly.

To switch on visual-line-mode per file, there are three options:

Put
```
# -*- eval: (visual-line-mode) -*-
```
in the first line of an Org mode file, or

Put

# Local Variables:
# eval: (visual-line-mode)
# End:

at the end of Org mode file

Put

* Dummy Heading         :noexport:
Local Variables:
eval: (visual-line-mode)
End:

at the end of Org mode file

For options 1. and 2. the # character marks the lines as Org mode comments, but Emacs picks them up anyway, and switches on the minor mode. For option 3. the lines are valid Org mode content, but the :noexport: tag inhibits the lines from being exported to HTML, LaTeX, etc.

I prefer option 1.

You might want to switch on visual-line-mode in every text-mode (which includes org-mode), like this in your init.el:

(add-hook 'text-mode-hook 'turn-on-visual-line-mode)

Nota bene, neither of those possibilities change the buffer in any way. They only change how the lines look on screen. If you want to change the buffer to physically "wrap" the lines, Emacs offers e.g. fill-paragraph. See here.

Show Images when Opening a File

Go to Org, Customize Group: Org Startup, Org Startup With Inline Images and set to non-nil. This writes

 '(org-startup-with-inline-images t)

to init.el

The same can be forced per file by putting

#+STARTUP: inlineimages

at the top in the file. See https://www.orgmode.org/manual/In_002dbuffer-settings.html

Simple To-Do List Set-up

As guidance used http://pragmaticemacs.com/emacs/org-mode-basics-vi-a-simple-todo-list/ and https://orgmode.org/worg/org-tutorials/orgtutorial_dto.html

To-do lists are headings marked TODO in ordinary org-mode files. Agendas are views onto such files generated by org-mode.

Setup

First I need to specify where org finds my to-do lists: the relevant variable is org-agenda-files. Its default is ".". Using Emacs' customise, I changed it to contain two files: ~/org/mytodo.org and ~/org/prj.org. The directory ~/org and the two files I had created before my self.

I choose two files, to learn how to split to-do items across multiple *.org files.

Test

Important commands:

C-c a t keystrokes to open the "global agenda" did not work. Going via the menu item worked.
g updates the agenda, when there changes in the do-do files
q closes the agenda.

How org-mode links open

You might want to determine, how links in org-mode files are opened, for example a link to the HOME directory:

[[~/.][Link to Home with no link type]]

[[file+emacs:~/.][Link to Home with link type file+emacs]]

Normally, mouse click or C-c C-o opens the link in Windows Explorer, if it is a directory. On MACOS it opens in Finder. Linux I need to find out.

I want to open the link by default in dired, rather than a GUI file manager in Linux. Searching the Internet showed:

C-u C-c C-o forces Emacs/dired (in a new frame)
file+emacs link type forces Emacs/dired (in a new frame)

Below is from https://emacs.stackexchange.com/questions/10426/org-mode-link-to-open-directory-in-dired

There are (at least) two ways. First, typing C-u C-c C-o on a link should force it to be opened in Emacs, rather than in an external app. Second, you can permanently override the default behavior by adding an entry to the variable org-file-apps:

(add-to-list 'org-file-apps '(directory . emacs))

which tells org-mode to use dired for all directory links. Alternatively, you could use customize-variable to achieve the same.

The reason that the default behavior is different between OS X and Linux is that org-file-apps-default-macosx contains a fall-through entry (t . "open %s")

You can modify the link description as follows :

[[file+emacs:~/projects][Projects]]

It will open the link in Emacs with typing C-c C-o.

FYI: it works but when M-x org-lint it shows

Deprecated "file+emacs" link type.

org-version 9.2.6 – junnu Oct 10 '19 at 13:22

Copying content from the Web

I often open web-pages using Emacs' eww-mode (M-x eww). There is the function org-eww-copy-for-org-mode (C-c C-x C-w) which copies from an eww buffer to the clipboard in a format suitable to insert in an org-mode buffer.

Interesting org-mode links

http://ehneilsen.net/notebook/orgExamples/org-examples.html