A Novel Approach to Writing with Atom and Markdown

In an earlier post, I explained how I used version control software to manage my creative writing documents. Since then, I’ve developed a setup that’s more transparent, easier to work with, and requires less command-line wizardry.

Most writers are probably used to creating documents in Microsoft Word, Google Docs, or some other word processing program. These programs offer a wealth of tools and options, but they all have one important limitation: they each use their own preferred format. A Word document, for example, will never look or behave exactly the same in Google Docs as it does in Office. Even software designed specifically for writers suffer from proprietary formats, as Stu Maschwitz eloquently explains on his blog Prolost. After trying dozens of different word processors and writing programs, I eventually got sick of playing the format game and decided on a totally different approach.

The Atomic Age

My approach starts with a program called Atom. Atom is a software development environment that can also be used as a plain text editor. Atom is open source (so anyone can contribute to it) and incredibly flexible thanks to its huge library of community-supported plugins. In addition to writing creative fiction, I also use Atom to write software documentation and program microcontrollers, and it works just as well in one task as it does in each of the others.

As versatile as it is, the important thing to remember is that Atom is not a word processor. It’s built for code rather than text, which requires you to think about writing in a different way. Where a word processor shows you the formatted document, a text editor like Atom shows you the code that creates the formatted document. The benefit is that the file itself is plain text and can be opened by any program that supports plain text files, even those that can’t interpret the code.

The language I use to create my documents is called Markdown. Markdown allows for basic formatting such as bold, italics, underlining, headers, tables, and lists. Fortunately Atom’s Markdown support is top-notch, since many developers use Markdown when documenting software projects.

Setting Up Atom

Atom lets you extend its features by downloading and installing packages. I currently use:

  • markdown-writer: Adds a variety of tools for writing in Markdown including keyboard shortcuts
  • markdown-preview-plus: Lets you view the rendered version of your document in real-time
  • markdown-scroll-sync: When previewing a document, this lets you scroll the edit and preview screens simultaneously
  • markdown-toc-auto: Automatically generates a table of contents using the document’s headers
  • tool-bar-markdown-writer: Adds a useful formatting toolbar to the top of the screen

Structuring Documents

For long-form fiction, I use a one-file-per-chapter approach where each chapter is a separate Markdown file. Chapters are named sequentially starting with “Chapter 01.md” (using two digits makes sorting much easier). Atom lists the contents of the folder in a Project overview pane on the left-hand side so you can quickly jump between files. You can also open multiple files in separate tabs or split the window between tabs so you can view multiple files simultaneously.

For projects with notes, I typically create a sub-folder with separate files for characters, setting details, plot details, etc. This folder also contains images, sounds, and other media files used as references. Unlike Word documents, Markdown doesn’t allow for embedded content, so you need to manually download and link files that you want to include in the document. I typically put these into a “Resources” sub-folder under the main project folder. However, you can skip this step if you’re linking to Web URLs instead of local files.

Keeping Everything Organized

As I mentioned in my earlier post, I manage all of my creative writing using Git. With Markdown, this becomes even easier. Since Markdown is plain text, you can see individual changes down to the letter. You can compare the current version of a file to a version from 5 months ago and see every re-work, every formatting change, and every fixed spelling error.

I also use Git branches as part of my workflow. Each draft gets a separate branch starting with “draft1”. When I’m done with the current draft, I’ll create a new branch for the next draft and switch to that branch, keeping the previous draft at its current state. Once the current draft is accepted as the final draft, I’ll merge the branch back into the master branch and delete each of the intermediate branches. This way, I can jump back to any of the previous drafts as needed without modifying the latest version of the document.

Atom comes with built-in tools and many community packages for managing Git repositories. The default package is designed for use with GitHub.com, but it works just as well with Git repositories hosted anywhere.

More Resources

To be fair, this approach is still rather techie and may not be suited to most writers. But I suggest you try it out and see if you like it. Here are some more resources you can turn to for more information.

Mastering Markdown” is an excellent beginner-oriented guide to writing in Markdown created by GitHub. GitHub is also the organization behind Atom.

The Ultimate Guide to Writing & Publishing with Markdown” by John O’ Nolan, CEO of Ghost.org, is another great Markdown guide geared more towards writers.

If you need a refresher on version control and Git, “Atlassian Git Tutorials” is always a great resource.

2 thoughts on “A Novel Approach to Writing with Atom and Markdown

  1. This is cool. I’m looking for a markdown editor for a book I’m writing. I want to be able to crosslink across chapters while also storing chapters in separate files. I’d also like to automate the table of content generation. Can atom do this stuff?

    1. You can do basic links and references pretty easily. I’ve only ever used inline links, so I can’t say how well any other type of link works.

      For my TOC, I use the markdown-toc-auto package for Atom. It auto-rebuilds the TOC each time you save using the document’s headers. You can set a custom min and max header level, whether to create links, etc.

Leave a Reply