Emacs for writing prose

Writing Prose While Doomed

The author Neal Stephenson has famously said that Emacs “might be thought of as a thermonuclear word processor.” Emacs, with org-mode, is an incredibly powerful set of tools for doing any sort of text manipulation. Doom collects a lot of the most powerful tools available in emacs, and provides handles that make using them much easier for a beginning user. If you’re reading this, you’re most likely familiar with Doom already, but even if you’re not, and you are interested in a powerful writing machine, I urge you to give Doom a try. As a professional writer, everything that I have had published, as well as my novel in progress, has been written almost entirely in emacs. I’ve tried many other methods, and I keep coming back to this infinitely powerful, infinitely configurable tool. Here are some of the tips that I have developed in my time using emacs for writing prose.

The majority of this article refers to writing in terms of books, but most of the same principles can be applied to short stories, articles, or anything else. Further, I use evil, so much of what I talk about here assumes those key bindings. Everything here works without evil, but you’ll need to consult the documentation if you want to use emacs-mode keybindings.

The outline is the text

Org-mode, of course, is a very powerful outliner. And, you can use it like you would any outliner to organize thoughts or make notes, but the real power of org-mode comes when you realize that you can treat the outline as the skeleton for the actual text of the book. The easiest way to do this is to create an org-mode outline for your entire book, and write the actual prose within the headers of the outline. This will allow you to move things around as you decide where sections go. If you’re a plotter, you can break things down in as much detail as you want:

* Act 1
** Chapter 1
*** Scene 1
**** We meet our protagonist
     It was a dark and stormy night...

Write actual text you mean to be published under a headline. The headline names are purely for your reference, and will not be exported, so you can name them useful and informative things. You can do any sort of outline you want here. For fiction, org-mode works particularly well for the The Snowflake Method or other methods where you work out sections in great detail, as org-mode allows you to fold and unfold sections to focus wherever you need.

If you’re a pantser, you can just write chunks of text in any order you want, and know that you can rely on org-mode’s ability to move headlines around to rearrange things later. Just try to break it up into manageable chunks. If you’re writing fiction, I recommend working at the scene level, but I know other writers who will go down to individual paragraphs per heading. Use whatever works for you. Org-mode is flexible.

Outline and write in fragments

Since you’re writing in outlines, you do not have to write things in order. Have an idea for a scene that needs to go later but you don’t know where? Just create a new heading, write as much of it as you want, then move it where it needs to go later. M-j and M-k move headers up and down, and M-h and M-l move them left or right, or, more technically, outdent and indent.

You can also use org-refile to move things around farther in your document. SPC r . will bring up a list of all the headers in the current buffer, and when you select one, the header you are on will be moved under that one. I use org-refile-to-visible, which is SPC m r v, constantly to see what different orders of events might look like.

Use tags

You can use tags to keep track of characters, arcs, or concepts easily. If you’re writing nonfiction, this can be a good way of keeping an eye on historical threads or conceptual themes so you can see that they are in balance. In my current novel in progress, this is one of my scene headers:

* Go to the Bar, find out he has been lied to :arcBreach: :charGodfrey:

This tells me that this scene is in the “Breach” story arc, and the character Godfrey appears in it. To add a tag to the header you’re on in Doom, type SPC m q. The colons aren’t part of the header names, those are automatically added by emacs to define tags.

Using org’s sparse-tree mode, you can easily see just the headings that match a specific tag, so you can rapidly get an overview of what you have where. In Doom, this is SPC m m m and then type the tag you want to see, which will be auto-completed by Ivy, so you’ll probably only need to type a few characters of it. This, also, is why I have “arc” and “char” before the two types of tags– by typing just “arc” here I can see a list of all the plot arcs I’m tracking.

One of my favorite tricks for tags is this: move the cursor to be on top of a tag, and do M-s h .. This will highlight all instances of that tag in the file. If you do it again for a different tag, you will get a different color of highlight. This way, you can see at a glance where all of your plot arcs are in relation to one another. To clear highlights, do M-s h u, which will give you a list of what’s currently highlighted, selecting one will remove it.

Narrowing and folding

Org-mode has lots of other tools for being able to selectively see what you’re working on. Folding the outline (using TAB and SHIFT-TAB) is the most obvious. There are also ways of increasing or decreasing the fold level to easily see various levels of overview. If you fold the entire document and do 2 z r, your outline will unfold to just the second level header. Depending on how regular your structure is, this can be an incredibly useful way of getting an overview. I recommend looking at the menu that pops up when you do z and exploring the options there, many of them can be quite useful.

Another feature that makes org-mode great is indirect buffers. This means you can have a buffer open with just the contents of one header, and can focus on that exclusively. If you do z n in a header, everything but that header will disappear. Note in the modeline there is now an icon that looks like two arrows squishing a line. That shows that you are in a narrowed buffer. To get out of it again, do z N. Narrowing buffers can also give you a marked speed increase when org is trying to deal with a 100,000 word file.

Often it can be useful to have the full outline in one window and the narrowed buffer in the other. This replicates somewhat the experience you might be used to from Scrivener or Ulysses. There are a few different ways to do this that can be found online, but this is what I use, which I found here (Frank Jonen has an entire emacs setup for prose writers. It’s designed to work with spacemacs, so it can’t be brought into Doom wholesale, but if you are comfortable understanding config files, it’s well worth looking at for ideas):

;; Split indirect buffer, via
;; https://github.com/frankjonen/emacs-for-writers/blob/898c9755598c8e689019b751f194e2e73b23bb03/.spacemacs

(defun my-split-and-indirect-orgtree ()
  "Splits window to the right and opens an org tree section in it"
  (interactive)
  (split-window-right)
  (windmove-right)
  (org-tree-to-indirect-buffer))

(defun my-kill-and-unsplit-orgtree ()
  "Kills the cloned buffer and deletes the window."
  (interactive)
  (kill-this-buffer)
  (delete-window))

This gives two new functions, accessible via M-x. The first creates a new window to the right with a narrowed buffer of the heading you’re on, and the second closes it. These could be easily mapped to keyboard shortcuts, but I haven’t needed to, so that is left as an exercise for the reader.

There is also a relatively new package, org-ol-tree, which provides an outline for a buffer that leverages treemacs for some extended capabilities. It’s in its infancy, but I’ve been using it consistently for about a week now and so far the results are really good.

Task states

Org-mode is, as the name suggests, usually used for organization, including to-do lists. You can use all of the functionality available in org-mode for tracking tasks to instead track the status of sections of your book. A lot of that is beyond the scope of this article, but there are a few things that are specifically helpful for writing.

I find it useful to use a separate group of TODO style states for the status of scenes in my book. My config file contains the following:

(setq org-todo-keywords
      '((sequence
         "TODO(t)"  ; A task that needs doing & is ready to do
         "PROJ(p)"  ; A project, which usually contains other tasks
         "NEXT(n)"  ; A task that is in progress
         "WAIT(t)"  ; Something external is holding up this task
         "HOLD(h)"  ; This task is paused/on hold because of me
         "OPEN(o)"  ; An open or ongoing loop
         "|"
         "DONE(d)"  ; Task successfully completed
         "KILL(K)") ; Task was cancelled, aborted or is no longer applicable
        (sequence
         "[ ](T)"   ; A task that needs doing
         "[-](S)"   ; Task is in progress
         "[?](W)"   ; Task is being held up or paused
         "|"
         "[X](D)")  ; Task was completed
        (sequence   ; adapted from Tony Ballantyne's writing methodology
         "IDEA(i!)"
         "WRITE(w!)"
         "EDIT(e!)"
         "WORKING(k!)"
         "|"
         "USED(u!/@)")))

This uses all of the todo keywords used by default by Doom (with a couple of adaptations for my preferred abbreviations, note the capital “K”), but adds a sequence specifically for story scenes in progress, which I got from Tony Ballantyne. This means that, while in a header, I do SPC m t e and I have marked that I need to come back and edit that scene later. These todo keywords, along with tags, can be very useful in creating custom agenda views to help you get any type of perspective of the work in progress that might be useful to you.

org-capture

But what if you have an idea for something else while you’re in the middle of a scene and just want to make a quick note without breaking your flow? This is where org-capture comes in. It allows you to pop up a window, write an idea down, and know where it will be filed so you can go back later.

SPC X brings up org-capture, and in fact it’s so useful, there is another binding for it under SPC n n, if that’s quicker for you. You’re going to want to create a custom capture template in your config file, so you can tell org-capture where you want things. Here is part of my config:

(setq org-capture-templates
      '(("t" "Todo" entry (file+headline "Todo.org" "00 INBOX")
         "* TODO %? \n %i ")
        ("n" "Novel Note" entry (file+headline "~/path/to/outline.org" "Novel Inbox")
         "* %?  \n  %i\n  %a ")))

So if I do SPC X n I get a minibuffer where I can write anything. When I hit C-c, that note becomes a new heading under the heading named “Novel Inbox” in the file outline.org, which is where I keep my book. Explaining the details of capture templates is beyond the scope of this article, but I will say that %a inserts a link to wherever I was when I made the note, so I have some context for what I was thinking when I wrote it, as it will inevitably make no sense the next morning.

Inline notes or links

And speaking of links, they are super useful when writing notes even when you are fully conscious. There are a couple of different ways of keeping notes for a work in progress using org-mode, and the way that works best for you will vary. I have a top-level header in my document for the body of the novel, and another one for notes. I also have a separate org file for more extensive notes, outline sketches, and general rambling as I work things out. I’m still experimenting with which of these works best for me. At the moment, I’m keeping actionable “things to do” in the file with the document, but this may change. With org-refile, mentioned above, it is easy to move things to another org file (this is done with SPC m r r) so I can change this any time I want. As long as a note has a link to what it references, it doesn’t really matter where you put it.

If you’re writing a note manually and not using org-capture, putting in a link is still simple. While inside the heading you wish to link to, do SPC n l. This will store a link. Then, go wherever you want to link from, and type SPC m l l and you’ll get an Ivy list of possible links. Very likely, the top one will be the one you just stored. Select it, and you will be prompted for the name for the link. If you ever want to re-name the link, if you do SPC m l t, all links in the document will be expanded, so you can edit them easily.

Note that if you want to ensure your links will work from other documents, you will probably want to set up using unique IDs for links. This Stackexchange answer gives a good explanation, but in my case, I just have this in my config:

(setq org-id-link-to-org-use-id 'create-if-interactive-and-no-custom-id)

And it works fine. It does create a properties drawer in each linked header, and you may find this irritating. If so, see that post for other options.

There are other ways to keep notes as well. Some people like to keep notes as a property drawer under each scene, though I find this unwieldy for anything other than a quick synopsis. If you are using tags to defined regions to be exported (see next section), anything not tagged for export can be a note. I frequently have headers next to a scene header not tagged for export, where I keep notes specific to that scene. This person has a method using #+NAME interspersed through the text as a way to link to individual paragraphs with notes. I find the buggy edge cases not worth the convenience of not having to scroll a bit, but if your text within a heading runs extra-long it may be worth looking into. Ultimately, you should find what works best for you, and emacs will almost certainly be able to work with your needs.

Export

So, assuming you have your notes in the same document as your book, how do you export just the book but not the notes? The answer, again, lies in tags. By default, if you tag a heading :export: it will be exported, and if you tag it with :noexport: it will not be. If you tag it :ignore: the header will also not be exported. There are many other details on how to selectively export in The Org Manual, and I encourage you to look into them. But as a cheater, this is what I have at the beginning of my document:

#+select_tags: prose
#+options: broken-links:t ':nil
#+options: toc:nil

“Select tags” makes it so I use :prose: instead of :export: as my export tag. I don’t really need this, but I have those headers tagged as prose for unrelated reasons, so it’s more convenient for me. “broken-links:t” ensures it will export even if it finds a broken link, “’:nil” makes export not use smart-quotes (which seems to break every export format I want to use, anyway), and “toc:nil” makes it not produce a table of contents on export.

Using this, I can export to markdown, docx, ODT, or pdf and get a clean copy of the novel without seeing any of the notes. This is very valuable for doing edits, because sometimes you just need to print it out and take a red pen to it.

A special consideration for writers who want to be traditionally published is the fact that the publishing industry largely runs on closed formats. At some point, you are going to have to leave org-mode and engage with edits in other, lesser formats. There is no good solution to this that I have found that does not involve convincing your editor to learn diff. However, there are a few resources online. How to write a book in Emacs - Mastering Emacs has a description for how he deals with this problem (using reStructured Text rather than org, but most of the principles should still apply).

Searching and movement

Emacs, and specifically Doom, has amazing tools for searching through documents which are very useful for the writer. The ones I use most often are:

  • SPC s s : Swiper. Just start typing, and you will get a live updated list of every result in the current buffer. Hit enter and you’re there.
  • SPC s S : same thing, but will search for whatever word your cursor is on by default. Very useful for finding all the places a character name shows up. Or seeing how badly I’ve overused the word “very” while writing this.
  • M-s o : Occur. Much like above, but will give the results in a persistent window that you can click on to go to results.
  • SPC n s : Search in notes. Will search through all of your org files.
  • SPC n S : org header search. Remember what you named the header for that scene you want? This will jump to it.

Oh, and SPC s O will let you search Google, Duckduckgo, Wikipedia, and various other online sources if you just need to get lost down a rabbit hole researching ancient Roman concrete technology. I mean, “do research”.

Emacs (especially with evil-mode) is also famous for its movement commands which allow you to rapidly go wherever you need to be quickly. Doom includes the lovely avy package, which has a number of configuration options for the way it allows you to choose what text to jump to, but I prefer avy-goto-char-timer. I have mine set up like this:

(setq avy-all-windows t)
(map! :leader
      :prefix "j"
      :desc "avy-goto-char-timer" "j" #'avy-goto-char-timer)

With this in my config, I do SPC j j and the first few characters of the word I’m looking at, and I can jump there with one key. The first line just ensures that this will happen in every window on the screen, so it’s also a quick way to jump to another window. It’s a bit hard to describe, so I recommend looking at the avy page which has nice screenshots showing each mode. Almost any of them will work in above code, with the appropriate replacement of names.

Another Doom-specific option for movement that is very helpful: g ; will jump backward through your most recent change in a file, and g , will jump forward in that list.

Just the words

No discussion of writing prose in Doom would be complete without mentioning zen-mode. Enable it by SPC t z. It will get rid of most interface elements, leaving you with nicely centered text which is easy to focus on. It’s just you and the words.

I’d explain it further, but no need. It’s zen.

Other packages

The emacs ecosystem is vast, and there are loads of packages that people have contributed that can make the prose writing experience better. Here’s a short list of some of the ones I use:

Word count

There are a number of options for tracking your word count in emacs. If you just want an ongoing word count in the modeline, do this:

(setq doom-modeline-enable-word-count t)

There are several packages available to do this in more complex ways, but the one I use is org-tracktable . It inserts a table into a header of your choice with a word count, the date, and the difference from the previous time you ran it, so you have a dated ongoing record of your progress. It also has options for setting goals and reporting how close you are to them. I found those unusably slow on my 70,000 word novel draft, so I don’t use them, but the table is worth it.

Palimpsest mode

Palimpsest does a good job of solving the problem of “I think I want to delete this but I’m not sure.” When you cut text with it, the cut text gets sent to the bottom of the file. Keep a header called Boneyard or something similar at the bottom of your document, and you always have what you cut out available when you change your mind.

Poet theme

Poet is a theme for emacs that is explicitly designed for working with prose. It does a very good job, and is very popular for this purpose.

Deft and org-roam for a story bible

Keeping track of whether each character has blue or brown eyes and which fictional country they are from is a job in and of itself. Many writers keep what they call a Story Bible to keep track of world building details. Conveniently, one of the best ways to do this is with a series of interlinked notes, which emacs excels at. I use a combination of org-roam and deft for this. But, in many cases, just org-mode links between items in a single document works just as well.

Links

Lastly, here are a few links to things other people have written about writing in emacs in general, not specific to Doom:

The title pretty much says it all. A longer and more detailed overview of what I’ve talked about here, with some great examples.

Inspirational and somewhat aspirational.

Diego Zamboni has a doom configuration which includes a lot of features oriented around prose writing. He also has a book about more specifically going from writing in org-mode to publishing with leanpub.

And here is a reddit thread from a few years ago that has some miscellaneous ideas that might be of use.

Conclusion

From the examples I’ve given here it should be apparent that org-mode within doom emacs is an immense tool for any sort of prose writing, and that harnessing the power of emacs with the ease-of-use of doom is a killer combination. I hope that this article gave you some ideas for using this combination that you didn’t have before. Actually, I hope you didn’t get this far in reading because you got too excited and had to go try things on your own. Regardless, enjoy your new thermonuclear word processor.

15 Likes

After a quick glance, we’re going to need to edit the lisp snippets at least to add syntax highlighting and the correct after! calls

For smart text autocompletion, I use company-tabnine.

org-tracktable is definitely the best word count package!

I am working on my new and improved Doom-Emacs powered creative writing environment, so I am probably going to write a new version of my “Creative Writing with Emacs” blog post :smiley:

4 Likes