markdown-novel-template: How to write a novel using Markdown, Pandoc, and Git

Contents

Introduction ⚓

For me, one of the difficult things about becoming a writer wasn’t figuring out what I wanted to write, but how I wanted to write. There are so many options for writers to get their thoughts down, from writer-centric applications like Scrivener 🔗 to “traditional” word processors like Microsoft Word and LibreOffice 🔗. Different tools suit different workflows, and each author’s workflow is unique. Finding the right tool can be just as challenging as starting the first page.

That’s why I created markdown-novel-template. This isn’t another tool, but rather a template for creating an entire novel, book, short story, or any form of literature of your choice, using just Markdown, git, and a terminal. In this post, I’ll explain why I made this project and how you can use it to (hopefully) simplify your own writing process.

The basics: What is Markdown? ⚓

markdown-novel-template is a way of writing long-form, chapter-based content using Markdown 🔗. If you’re unfamiliar, Markdown is a language for formatting text much like a typical word processor. It’s designed to be lightweight, easy to understand, and easy to write. A Markdown file is just a plain text file with some formatting symbols. In fact, this entire website is written in Markdown and converted to HTML when I publish it.

Why Markdown for writers? ⚓

Markdown is typically used by software developers to write code documentation (think “ReadMe” files). This is because it’s easy to work with, a lot of program languages and frameworks support or use it, and the files are plain text files, so it’s easy to compare changes. You can open a Markdown file in a plain text editor like Notepad and understand exactly what its contents are and how it’s meant to appear. You can even track changes to a Markdown file using version control software 🔗 like git 🔗, just like source code.

For writers, Markdown provides a lot of benefits:

• It’s portable: Markdown editing tools are available for Windows, macOS, Linux, Android, iOS, and almost any other OS you can think of.
• You can easily sync Markdown files using tools like Dropbox, OneDrive, or Nextcloud.
• The files are incredibly small in size, so you don’t need to worry about needing tons of storage space.
• Markdown is a stable standard: a Markdown file from 2005 will look the same way today as it did 18 years ago.

It’s more limited than formats like DOCX, but when you’re writing fiction, you don’t really need a lot of features and flashiness. Because Markdown is an open standard, many different tools support reading and editing it. I use Typora 🔗, but there are dozens of other options 🔗.

Structuring your work as a Markdown writer ⚓

Because Markdown is just a language, it’s up to you to figure out how to structure your projects. This includes creating, organizing, combining, and exporting your Markdown files into a final book. My approach to doing this is simple:

• Create a folder for the project.
• Create two subfolders: content for the content that will be in my book, and notes for things like storyboards, character sheets, and reference images.
• In the content folder, create a separate Markdown file for each chapter/section of the book.

Exporting a single book is as easy as combining each of the individual Markdown files in the content folder. Since they’re all plain text, you can just create a new Markdown file and append each one to it. That’s really all markdown-novel-template does: it creates this folder structure for you and provides tools for merging your chapters into a single document.

How to use markdown-novel-template ⚓

Ready to give it a try? First, grab the latest version from GitHub 🔗. You should end up with a ZIP file called (unsurprisingly) “markdown-novel-template.zip.” Unzip this file.

In this folder are two folders: content and notes. The content folder is for text that you want to have show up in your book. This mainly means chapters, but it also includes things like appendices, copyright pages, dedication pages, and other front and back-matter (you don’t need to create a table of contents or title page, as this project does that for you). There are a few sample files you can use to get an idea of how to start.

Keep in mind that this project will merge these files in alphabetical order, so name them accordingly!

The notes folder is for any files that are relevant to this project, but you don’t want to have appear in your final book. This can be things like author notes, character reference sheets, research, media files, or any other files you want to include. This folder’s empty, and for good reason: I have no way of knowing what/how you keep notes, so I leave it to you to use this folder however you want!

In the main folder are a few standalone files, but here are the most important ones:

• metadata.yml stores information about your book, including the title and subtitle, the author’s name (that’s you!), the date of publication, and the language. There’s some extra stuff in there, but you can ignore it—it’s mainly for the compilation process.
• cover.png is where your cover image goes. If you don’t have one, that’s fine—you can use the default, or just delete this file altogether.
• compile.sh is where the magic happens. When you’re done with your book, just run this script in a terminal and it will automagically generate a complete draft in Markdown, DOCX, PDF, and EPUB formats. This draft is dropped in a newly created subfolder named drafts.

Compiling your book ⚓

Once you have all your content ready to go and want to actually build your book, that’s what the compile.sh script is for. This script does a handful of things:

1. It pulls your individual Markdown files into a single, large, combined Markdown file.
2. It converts this file into DOCX, EPUB, and PDF using a tool called pandoc 🔗.

It will name the draft file/folder after the name of your current Git branch 🔗. This assumes that you create a new branch for each draft. If not, your draft will be created in the drafts/main folder.

Note: This script requires find 🔗, pandoc 🔗, pandoc-crossref 🔗, and the texlive core to be installed.

Just run the following command in the markdown-novel-template directory:

./compile.sh

And check the drafts folder for your new draft!

Tweaking the template ⚓

If you don’t like the default options for the drafts, or you want to generate a different file, you can always change the compile.sh script and add or remove pandoc commands. You can name the files in content/ however you want and structure them however they want (just remember to keep them in alphabetical order). And if you want to change the cover page, remember to change the metadata.yml file.

If you want to contribute changes to the project itself, checkout the GitHub repository at https://github.com/8bitbuddhist/markdown-novel-template 🔗. Pull requests are always welcome!