Emacs Org Mode for Distraction-Free Writing

To start an Org file, create a file with a .org extension and start writing, for example, C-x C-f test.org <Enter>.

Each Org document starts with a header that contains metadata and settings relevant to the buffer. The Org mode metadata and settings start with #+ followed by a keyword and a colon. The document header can also contain metadata such as a subtitle or a date. Emacs packages can use this information when publishing the text and other functionality.

  #+title:   Lorem Ipsum
  #+author:  Nomen Nescio
  #+date:    [2021-05-08 Sat]

Org mode recognises several other types of front matter items to control exporting and other behaviours, some of which are mentioned below.

Your chosen Emacs theme will set the size and font for your document. The only purpose of these decorations is to help you navigate the document. The article about publishing articles and books with Org mode shows how to control the output format.

Books have chapters, sections and paragraphs; articles have headings; poems have verses; and so on. Almost all forms of writing have a hierarchy. An excellent method to start writing is to work out your hierarchical structure and fill it with content.

Org mode is an outlining tool that helps you develop a document structure. Write an asterisk as the first character to start a new header, followed by a space. To create deeper levels, add more stars:

  * Heading 1
  ** Heading 2
  *** Heading 3

When you press M-enter, the following line becomes a new heading. With C-enter, the next line is added after the text in the current section.

Org mode makes it easy to move and promote or demote headings and associated text (which in Org mode is a subtree) with the ALT and arrow keys.

You can collapse or expand a heading with the TAB key. Pressing S-TAB will collapse the document, showing only the level one headings. Pressing S-TAB once again will show the headings, and repeating it for a second time reveals the entire buffer. You can keep cycling through these modes with the S-TAB key.

• TAB / S-TAB: (un)fold headings
• M-up / M-down: move a headline up or down
• M-left / M-right: promote or demote a headline
• M-RET: insert a new headline

Add numbers to the headers with the num option in the startup line: #+startup: num. Whether this numbering appears in any published output depends on your configuration.

To change how Org Mode displays text, you surround it with special characters: /italic/, *bold*, _underline_, +striketrough+ and =verbatim=. You will see these markers in the Org mode text, but they disappear when you export the buffer.

Writing lists in Org mode could not be easier. Simply start a line with a dash and complete the entry with M-ENTER to create the next entry. Using the TAB and left or right arrow keys changes the depth of the item and, with the up and down arrows, moves the line up or down in the hierarchy. Change the list prefix with the SHIFT and left/right arrow keys.

  - Item
    + next item
      1. The following
      2. And another
         a. Down, down, deeper and down

The following configuration line enables alphabetically ordered lists as well as numerals.

  (use-package org
    :custom
    (org-list-allow-alphabetical t))

Every cell in an Org mode table is flanked by the pipe | symbol. You don't have to worry about aligning the text, as the TAB key does that for you. You create a horizontal line when you start a line with |- and hit TAB.

| Column 1 | Column 2 |
|----------+----------|
| Sator    |       12 |
| Arepo    |       26 |
| Tenet    |      878 |
| Opera    |       89 |
| Rotas    |       89 |

You navigate forward through the cells with the TAB or arrow up/down keys. Using s-TAB moves you back one cell. Combining Alt and Shift with the arrow keys adds and removes columns and rows.

Org mode has extensive capabilities to edit tables, including formulas to create spreadsheet functionality.

Although Emacs is a text editor, it can also manage images. In Org mode, an image is a link to an image file. You can preview the file in your buffer or export it to your preferred format. You can also add captions and set display or export properties for each image.

  #+caption: Image caption.
  #+attr_html: :alt Alternative text
  [[file:path/to/image]]

To view the preview images in your document or remove the previews, you press C-c C-x C-v (org-toggle-inline-images). You can also add #+startup: inlineimages to view images by default for the buffer.

To add an image, press C-c C-l (org-insert-link), which opens the link menu. Org mode understands many types of links. We want the file type, so type file:. Press enter and select the image filename in the mini buffer. You can skip the file part with the C-u C-c C-l shortcut (adding C-u before the standard shortcut.)

After adding the image, you preview it with the org-redisplay-inline-images function or C-c C-x C-M-v.

You open a link in Org mode with a mouse click or by pressing C-c C-o (org-open-at-point) with your cursor on the link text. Emacs has some facilities to manage image libraries through the image-dired package.

The images in the buffer are all shown at the same width, which you can configure to meet your needs. The articles about writing articles and books with Emacs and the article about creating websites with Emacs explains how to control image size and other image properties.

Emacs Writing Studio provides a convenience function to insert images from screenshots, which is bound to the Control-PrintScreen key. This function asks for a filename (and forces a PNG extension). The user then selects a partial screenshot and a caption. The function then inserts the image link and caption.

  (defun ews-org-insert-screenshot ()
    "Take a screenshot with ImageMagick and insert as an Org mode link."
    (interactive)
    (let ((filename (read-file-name "Enter filename for screenshot: " default-directory)))
      (unless (string-equal "png" (file-name-extension filename))
        (setq filename (concat (file-name-sans-extension filename) ".png")))
      (call-process-shell-command (format "import %s" filename))
      (insert (format "#+caption: %s\n" (read-from-minibuffer "Caption: ")))
      (insert (format "[[file:%s]]" filename))
      (org-redisplay-inline-images)))

  (with-eval-after-load "org"
    (define-key org-mode-map (kbd "C-<print>") #'ews-org-insert-screenshot))

Org mode will number every heading when the #+startup: num option is set. The numbering will appear in the Org file. How numbering is treated in the export depends on the file format you use.

In some publications, not all headers are numbered, such as in the front matter of a book. You can exclude individual sections from being numbered by setting the :unnumbered: property as shown below. To add this property, drawer, type C-c C-x p, select the relevant property and enter the value.

:PROPERTIES:
:UNNUMBERED: t
:END:

Writing a book in a single Org mode file can be laborious because you need to navigate a large file. The built-in narrowing tool can help in keeping your focus. Narrowing in Emacs means that the buffer will only show a selected part of your text so you don't get distracted by the rest of the document. The hidden text is still available, just not visible on the screen.

To narrow your buffer to only show the subtree (heading and associated subheadings) you are currently working in use org-narrow-to-subtree (C-x n s). This commands reduces the visible text to the section under consideration. To go back to the full document evaluate the widen command (C-x n w).

Sometimes it might be a good idea to split larger projects over multiple files. Org mode has an inclusion function that creates a link between documents.

The #+include: "chapter-02.org" line includes a file named Chapter 02 inside the main document. You can visit this child document with C-c ' (org-edit-special). Org mode has some additional options to determine exactly which part of the child document is included.

This method allows you to work on a book or dissertation and store each chapter in a separate file. When you export the main file to a PDF, or ePUB file, all included files are added to the export.

Sometimes, adding notes to your text that should be separate from the final version is worthwhile. You should add a checklist of what needs to be done, links to websites or notes in your Denote digital garden, or anything else of importance during the process of writing.

Any line in Org mode that starts with a hashtag or pound symbol is a comment, which Emacs ignores when exporting the text to the final output.

  # This is a comment

Org mode also has handy drawers, which are bits of collapsible text that can store notes. You can keep multiple lines of text in a drawer, for example, if you need to cut out a bit of text and would like to save it for future reference. The beauty of Org mode drawers is that they are collapsible, so their contents do not distract you from the primary task. You can close or open a drawer with the TAB key when the cursor is on the drawer.

  ** This is a headline
  :DRAWER_NAME:
  This is inside the drawer.
  :END:
  
  After the drawer.

You can interactively insert a drawer at point by calling the org-insert-drawer, bound to C-c C-x d. The selected text will be placed inside the drawer when a region is active. This function will add the name for your drawer, usually written in full caps. The drawer is inserted at the current location of the cursor.

An Emacs Writing Studio function (ews-org-insert-notes-drawer) generates notes drawers, bound to the C-c C-x n keyboard shortcut. This function jumps just below the heading of the section you are writing and generates a notes drawer. If a drawer exists for this section, a new line is created at the end of the current note. After you finish writing the note, C-u C-SPACE will take you back to your original position in the text.

  ;; Notes drawers
  (defun ews-org-insert-notes-drawer ()
    "Generate or open a NOTES drawer under the current heading."
    (interactive)
    (push-mark)
    (org-previous-visible-heading 1)
    (next-line)
    (org-beginning-of-line)
    (if (looking-at-p "^[ \t]*:NOTES:")
        (progn
          (org-fold-hide-drawer-toggle 'off)
          (re-search-forward "^[ \t]*:END:" nil t)
          (previous-line)
          (org-end-of-line)
          (org-return))
      (org-insert-drawer nil "NOTES"))
    (org-unlogged-message "Press <C-u C-SPACE> to return to the previous position."))

  (with-eval-after-load "org"
    (define-key org-mode-map (kbd "C-c C-x n") #'ews-org-insert-notes-drawer))

If you need to take any notes unrelated to the document at hand, then a fleeting note stored in your central inbox is a better choice. The Org mode capture mechanism is the best solution for these situations.

Emacs has a built-in functionality to count words in a region using the count-words-region function (M ==). To find out how many words each chapter or section of your work has, you will need to run this for each part of your document. Within Org mode, there is an easy way to automate this behaviour and get an almost instant overview of your word count for each document part. This method will also let you add word count targets for each section so you can monitor progress or balance your writing.

Org mode can add properties to each heading, which we can leverage to add word counts. To add a property, use C-c C-x p and select one from the list or create a new one. The ews-org-count-words function cycles through all headings in your open Org buffer and adds a word count for each heading, including the subheadings. To add a target word count, add a new property called target and add the relevant number.

  (defun ews-org-count-words ()
    "Add word count to each heading property drawer in an Org mode buffer."
    (interactive)
    (org-map-entries
     (lambda ()
       (let* ((start (point))
              (end (save-excursion (org-end-of-subtree)))
              (word-count (count-words start end)))
         (org-set-property "wordcount" (number-to-string word-count))
         (unless (org-entry-get nil "target")
           (org-set-property "target" "0"))))))

A collapsible property drawer shows a word count and your manually added target. When no target property exists yet, this function will add one with zero as a default. This property drawer works the same way as the notes drawer discussed previously.

  :PROPERTIES:
  :wordcount: 305
  :target: 300
  :END:

You can view the word count for each heading in Org mode's property column view C-c C-x c (org-columns). Ensure you evaluate this function at the highest level (beginning of the document). Org mode only shows the properties for the subtree you are currently in. This view creates an overlay. By cylcing through the document with S-TAB, a table will appear. To include the word counts and targets, you will need to add this line at the start of the document, which defines which properties to see in each column :

  #+columns: %40item %10todo %10wordcount %10target

The columns are an overlay and not part of the text, so nothing you wrote is modified. You can keep editing your document in column view. Place the cursor on a column overlay to remove the overlay and press q.

As you are working on various parts of your writing project it might be godo to know what the status of each chapter is.

Org mode also has an extensive system to manage projects, which you can also deploy to keep track of progress in your document.

Each heading in Org mode can have a status token, such as TODO, DONE or EDITED, or whatever workflow you like to use. You add a status token with the shift and left/right arrow keys when the cursor is on a heading. You can also use the C-c C-t shortcut (org-todo).

By default, the system only uses the TODO and DONE status. You can add additional workflow states by defining them in the document header. The example below will cycle through these four status tokens. The tokens before the vertical line are in progress and usually marked in red. The vertical line are completed and marked in green. Org mode will add a timestamp when a section gets to the FINAL status in this example.

  #+todo: WRITE DRAFT EDIT | FINAL

Org mode has extensive facilities to fine tune how these status tokens behave, including adding notes and timestamps.

This article only covered the tip of the iceberg of the writing and editing functionality in Emacs. Many specialised packages are available to enhance your writing experience. I advise keeping it simple for now and spend your tie writing instead of configuring Emacs. When you discover a new need, a few Google searches will often give you exactly what you need.