Writing a novel with markdown… and git

Chris Rosser
3 min readNov 4, 2022

I know… 🤯 but bear with me. In my day job as a technical writer, I’ve written docs as code exclusively for 10 years. The reason is simple: the methodology is more efficient, durable and flexible. I reap enormous productivity benefits when my work is under revision control in a format that’s indestructible and easy to manipulate and publish.

Yet, for several reasons — mostly thanks to my entrenched use of Scrivener — I’ve always thought that writing fiction as code was unnecessary, and perhaps even detrimental to the creative process. However, adopting these practices and tools can yield all the benefits I enjoy as a technical writer, namely:

  • No vendor lock-in thanks to an open format (plain text).
  • Use any text editor I want, be it proprietary or open-source.
  • Change tools during the project lifecycle, using whatever bests suits what I’m doing, i.e. draft in Ulysses, edit in VS Code.
  • Harness the power of command-line utilities and scripting languages to automate the editorial and publishing process.
  • Commit, branch, diff/compare, and store my project in a secure, private GitHub repository.

These are pretty nerdy benefits, and your average fiction writer might struggle to see a usable workflow that mirrors what a novelist might expect when using something like Scrivener, Word or Google Docs. So, let’s consider how these might translate into a workable solution.

In summary, write with markdown, organise with git.

Being late in 2022 I don’t think I need to introduce what markdown is any more, suffice to say it’s a lightweight syntax that adds formatting to plain-text files. Writers of prose need very little in the way of formatting while they draft, making markdown ideally suited for novelists.

Git, however, is likely to be unfamiliar to most writers outside technical circles, so it deserves an explanation. At its heart, Git is version-control software that tracks changes to files. It can track any kind of file, but is ideally suited to plain text, most commonly written as source code for computer programs and web apps. Since markdown is plain text, it can benefit from git in the same way as source code, hence the expression docs as code.

Git is open-source software, and is available to install on all operating systems — even on mobile platforms. It runs primarily on the command line, but there are apps available to those who prefer to work in a graphical environment. It also works on servers, powering services like GitHub, BitBucket and GitLab, which you can use to securely back up your work in private repositories for free.

So, how would this work?

  1. Create a free account on your Git service of choice (or self-host), and then create a private repository for your project.
  2. Install the git client for your computer’s operating system, and clone your remote (i.e. GitHub) repository to a local directory.
  3. Write your files in markdown, using whatever text editor you like. iA Writer and Ulysses are good choices for writers of prose, as they attempt to abstract some of markdown’s ugliness. Optionally, you can use a traditional programmer’s editor such as VS Code, which does an impressive job handling both markdown and git.
  4. Commit your work to a branch, for example, one named first-draft.
  5. Push your committed changes to GitHub to ensure they are backed up and secure.
  6. Rinse and repeat steps 3 to 5 as your project grows.
  7. As you reach a project milestone, for example, completing your first draft, create new branches to preserve your drafts in their original state — this is one of Git’s most powerful features.
  8. When you’ve finished, transform your markdown documents for publication in the format of your choice.

Okay, so I’ve grossly over simplified things, but the intent was to give an overview. It’s a thought experiment I’ve been running in my head since I learnt an author I’m friendly with on Twitter experienced a disaster with Scrivener that effectively locked her out of the app. I also quietly switched from Scrivener to Ulysses when I started my current novel, which I serialise to my readers, a use case that Scrivener turned out to be really lousy at, thanks to its monolithic structure. So, I’ve been quietly writing fiction in markdown now for more than a year.

Given interest, I think I’d like to expand this post into a series. The idea would be to apply this theory to a more practical workflow, namely on how I would replace Scrivener with a writing system based on Markdown and Git. If that interests you, do let me know in the comments.

--

--

Chris Rosser

Technical writer and occasional author sharing thoughts on creativity, productivity and technology. Works at Canva. https://chrisrosser.substack.com