Writing a Book in Markdown with Version Control

I’ve long enjoyed a love-hate relationship with Scrivener, the all-in-one writing platform for novels, short stories, textbooks and other written endeavors. I love it because it offers excellent outlining and note-taking features, plus it integrates with programs like Scapple for mind-mapping and Aeon Timeline 2 for timeline management. Scrivener supports many different compile settings, so exporting content is never a challenge.
hate it, though, because Scrivener’s full-screen editor is abysmal—the worst “distraction-free” implementation I’ve ever seen in any app that supports this feature—and because Scrivener projects are essentially a giant cluster of Rich Text Format files named by number and stored in a byzantine file-tree structure, separating me from my work by requiring the application to mediate my content.
My preferred approach to writing is to enter a full-screen, distraction-free mode. (Usually after dark, in an unlit room, working with an amber-on-chocolate color scheme, with soft music playing and either the windows open to the breeze or a fire roaring in the fireplace.) Over the years, I’ve played with different approaches to writing in Markdown with a dedicated text editor, but these efforts haven’t proven satisfactory because the apps tend to take a single window and full-screen it, cutting me off from my notes.
Until recently, when Microsoft’s Visual Studio Code allowed for multi-pane windows, even in distraction-free mode. Whoa. Yes, I know you can open multiple simultaneous buffers in Emacs or whatnot, but my willingness to learn Emacs or Vim syntax remains too weak to justify the technical debt of mastering these systems just to write. So VS Code, which is much simpler, fills me with joy.

Work in progress.

I played with it and got hooked. And because VS Code does a great job of working with the git system, I explored even more deeply with version-control on my text documents. I’m now far enough into the process to have decided that I’m migrating all of my writing out of Scrivener and into my new infrastructure.
I’ll share how I set up this environment in the context of a book I’m writing about healthcare data analytics, and then why I think plain-text writing with version control makes more sense for complex writing projects.

The Setup Process

After initial testing seemed favorable, I created a DigitalOcean droplet with a one-click install of GitLab Community Edition. GitLab CE is a free, open-sourced platform for storing and sharing computer code, with enhancements designed to make the code-writing job easier. I’m paying $10/month for the DO droplet (a droplet is a virtual server, in this case, an implementation of Ubuntu Linux that already has GitLab CE configured on it, so I didn’t have to do any tedious manual installations). I use DO to host this website, and the jegillikin.com domain name, so I mapped the new droplet to a subdomain—gitlab.jegillikin.com. This approach is significant because I can add new users to my GitLab environment with permissions to participate in one or more projects as collaborators, without having to email Word documents back-and-forth. Less tech-savvy collaborators may simply use the built-in Web editor to work, without having to download or install or configure anything.
It took roughly 10 minutes to fine-tune the GitLab installation after the droplet was set up. Perform the usual Ubuntu security-hardening steps, and voila. Good to go.
I downloaded the most current release of Visual Studio Code (the app receives updates monthly) and then installed a few specific extensions to make my drafting process easier:

  • Active File in Statusbar—to show the file path in the status bar
  • Amber Theme—the colors I want, amber-on-chocolate
  • Anaconda Extension Pack—tweaks and settings optimized for the Anaconda Scientific Python distribution
  • Bookmarks—ability to mark specific lines and then jump between them
  • Clock in Status Bar—adds a small clock, useful in the distraction-free mode
  • Code Settings Sync — syncs your complete configuration to GitHub (not GitLab) so you can clone your setup on a different computer or a re-installed computer
  • Markdownlint—a linting/style-checking tool for Markdown
  • Markdown TOC—auto-generates a table of contents based on internal headings
  • Spell Right—a lightweight spell checker
  • VScode-Spotify—integration so I can manipulate a Spotify playlist from the VS Code taskbar (so no more getting out full-screen mode just to adjust my tunes)
  • VScode-Timer—a simple configurable countdown timer that sits in the statusbar
  • VScode-YAML—a linter for YAML
  • WordCounter—a counter, in the status bar, showing the number of words, characters and lines, as well as the estimated reading time for the file

I also tweaked a few VS Code stock settings to my liking, including font choice (I’m a fan of monospaced fonts for writing, so I use Liberation Mono) and color swaps for the statusbar.
You’ll also need to down the Github for Desktop client. The Github client works just fine with a GitLab server. The client installs git on your computer. VS Code uses git to push and pull content between your local machine and the GitLab CE server.
With the server and the software configured, the next step was to create a project. More than one way to do it. I opted to create it in the GitLab CE control panel, then I used the Github for Desktop client to clone repository, selecting the URL of my GitLab project and a folder on my PC. (Bonus: I sync the local folder witihn my OneDrive structure, so there’s yet another cloud backup lurking out there.)

The Writing Process

With a cloned repository, whatever you write on your local computer—as long as the file is stored in the folder you selected when you cloned it—will sync with the server. Unlike tools like OneDrive or Dropbox or Google Drive, syncing with git isn’t automatic, however. You only sync when you want to. When you do sync (in a process called a commit), you’ll be prompted to add optional change notes. I find it helpful to offer a sentence or two summarizing what I just did. Every sync creates a new revision, or current-state snapshot of the project, and all of those revisions are maintained. So if you work on the same chapter over three months and commit changes 36 times, you’ll be able to check all 36 versions and even compare them—like “what’s different between version 23 and version 32?”).
That said, writing is straightforward. Just write. Don’t worry about formatting or margins or fonts: All of those concepts are superfluous during the drafting process when you’re working with Markdown. Instead, just write. And commit changes frequently. Any specific formatting requirements, like headings or bold/italic typefaces or lists, are effected in a straightforward manner using Markdown syntax within the file.

Why Markdown Plus Version Control Rocks for Complex Writing

One thing’s for sure: You must be reasonably comfortable using a text editor (instead of a word processor) to write in order to thrive in this production model. And you must possess some expertise in working with a version-control system, although you’re free to either use GitLab’s free online service or subscribe to GitLab or GitHub so you don’t need to run your own server.
But the benefits to this drafting process are substantial:

  • Although Microsoft Word is a very capable application for writing complex long-form projects, not many users know how to use Word optimally. As such, file corruption and the need for complex reformatting can suck away at precious writing/editing time.
  • Version control means you don’t need to save a billion different copies of a file, each with a slightly different name. And, you can compare those files easily. And because your files are committed to the repository, you don’t run the risk of losing “all your work” if your thumb drive gets lost or your hard drive crashes.
  • A VCS with an online portal—like GitLab CE—opens the door to tightly controlled access to specific files, protecting your intellectual property and facilitating broad collaboration with other contributors, without the need to email drafts back-and-forth and then harmonize them by hand. In fact, GitLab CE contains an issue-management system, so edits and questions remain with the project and accessible to all contributors.
  • Markdown makes you focus on your content, not on how the content looks on the screen. Text in Markdown converts to anything by means of tools like Pandoc. Plain text is the one file type that will never become obsolete.
  • Tools like VS Code (and, admittedly, Emacs, Vim, Notepad++, Atom and countless other text editors) support high degrees of customization, so you can write how you want without being locked into the fixed interface options of Word, Scrivener, etc. Don’t be misled into thinking that text editors are only for hard-core computer programmers. Plain-text writing in Markdown is absolutely a valid and supported use case for these software platforms.

Las Vegas Trip Report

The period between returning from Quebec and hoofin’ it to The Happiest Place on Earth™ stretched three long weeks—and by long, I mean “lots to do.” Holy moly. You’d think that not having a corporate 9-to-5 day job would free up copious amounts of time, but I learned that (a) accumulated catch-up takes a long time […]

Continue Reading

18 Years Later …

On July 7, 2000, I accepted employment as an administrative project coordinator with the nursing resource center at Spectrum Health. The organization—then just three tumultuous years into the merger between Butterworth Hospital and Blodgett Memorial Medical Center, and under a strict federal consent degree to boot—offered no benefits for my temporary/on-call role, but it did […]

Continue Reading

Reading Challenge: First Quarter Results

In December I said to myself, “Self, I need to read more books for fun”—instead of reading books that I had to address as part of my Caffeinated Press duties. So I accepted my own challenge and set a goal of completing one book per month. So far, I’m ahead of schedule. In January, I […]

Continue Reading

Days Flying By

A few weeks ago I remarked to some colleagues that it seemed both too early and too late for the beginning of March to have arrived. By that, I meant that so much has happened that time is flying by. But, flip side, it’s only just March. Time’s also draggin’ along. Some recent highlights, in no […]

Continue Reading

Writing Tools

I’ve been on a bit of an electronics consolidation tear lately. A few months ago, I bought a new desktop computer rig (7th-gen Core i7 processor, 16 GB RAM, 250 GB SSD, 1 TB HDD and an Nvidia GTX-1060 GPU) to replace my all-in-one machine with aged specs and a failing connection between the integrated […]

Continue Reading