Four years ago, I wrote a Reddit post about why I switched to pure text files instead of using Microsoft Word, Libreoffice, or even Google Docs. The short answer is: text is forever and it is really hard to corrupt a text document.

There was a secondary reason for using text format and that was because I like keeping track of metadata while I write. A lot of authors do, actually, but I didn't care for the more common methods of keeping a spreadsheet in sync with the writing or getting Scrivner to behave. At the time, it wasn't so great, from what I've seen, a lot of what I do here can also be done in that program. That said, I still don't use it because of their file format doesn't play well with Git (I wrote a post about that last year).

Now, I have been doing this for a while. However, last year, someone at WisCon asked me about it and I thought I made the post but apparently I didn't. Today, someone asked me the same question ("how do you use Markdown and YAML to write?") and I went to point them to my article I didn't write last year and realized that I didn't write it.

So… here it is.

Format

When I write, the basic file looks like this:

---
title: Rutejìmo
---

> When a child is waiting to become an adult, they are subtly encouraged
> to prove themselves ready for the rites of passage. In public, however,
> they are to remain patient and respectful. --- Funikogo Ganósho, *The
> Wait in the Valleys*

Rutejìmo's heart slammed against his ribs as he held himself still. The
cool desert wind blew across his face, teasing his short, dark hair. In the
night, his brown skin was lost to the shadows, but he would be exposed if
anyone shone a lantern toward the top of the small building. Fortunately,
the shrine house was at the southern end of the Shimusogo Valley, the
clan's ancestral home, and very few of the clan went there except for
meetings and prayers.

The > is a block quote which I use for my epigraphs. There is a quote at the beginning of every chapter for world building. Everything after that is Markdown. I use *italics* and **bold** but otherwise not a lot.

Front Matter

The really important part is the YAML front matter. I picked YAML because it was really easy to read and change. It also parsed very well by computers. The only thing I don't like is that it doesn't like tabs… but can't be perfect.

There is a lot more in this header than I showed above. For the first chapter of Sand and Blood, the front matter looks like this:

---
availability: public
when: 1471/3/28 MTR
duration: 25 gm
title: Rutejìmo
locations:
  primary:
    - Shimusogo Valley
characters:
  primary:
    - Shimusogo Rutejìmo
  secondary:
    - Shimusogo Hyonèku
purpose:
  - Introduce Rutejìmo
  - Introduce Hyonèku
  - Introduce naming conventions
  - Introduce formality rules
summary: >
  Rutejìmo was on top of the clan's shrine roof trying to sneak in and
  steal his grandfather's ashes. It was a teenage game, but also one to
  prove that he was capable of becoming an adult. He ended up falling off
  the roof.

  The shrine guard, Hyonèku, caught him before he hurt himself. After a
  few humiliating comments, he gave Rutejìmo a choice: tell the clan elder
  or tell his grandmother. Neither choice was good, but Rutejìmo decided to
  tell his grandmother.
---

As you might be able to tell, I keep a fair amount of information in the top of my files. This basically contains references to characters, locations, why the chapter exists. I could also put tone (action scene, introspection), scene types (scene or sequel), or anything else I want.

The nice reason for this is when I rename or arrange the file, the header goes with it. If I need to list all chapters that have a character references, I can with a simple “find in files”.

I also have it tied into a future plan of creating a master book that has every novel I have with the chapters interspersed so the entire world is chronological. I think it will be cool once I start overlapping these stories. I also plan on having locations so I can show them on the map, if I ever write it down.

Tools

Now, “find in files” can only go so far. Over the years, I've written a number of tools to help me work with these type of files. I've tried it out in Python, Perl, C#. Most of them have bits and pieces that work, I actually use a combination of all of them.

Today, I realized I was tired of working with tools from three different languages so I decided to add a fourth language that works with some future plans I have: Typescript. So, over my lunch and while kids were showing up the door for treating, I got the first version of Markdowny written.

npm install --global markdowny

markdowny basically duplicates the most common functionality I use from the other languages and puts it into a fairly generic framework that can show off the usefulness of using YAML.

Counting

The major drawback of YAML headers is that it is hard to figure out how many words something is. The built-in word count features of most editors counts the large YAML. So, markdowny has a simple feature for giving me a chapter-by-chapter breakdown of word lengths without the headers.

markdowny count chapters/*.markdown --total

The output is pretty simple actually. I mostly use this to select the chapters I want to submit to the writing group; we have a four thousand word limit with submissions.

chapter-01.markdown:  1,520
chapter-02.markdown:  2,144
chapter-03.markdown:  2,908
chapter-04.markdown:  1,173
chapter-05.markdown:  2,570
Totals             : 10,315

If you don't include the --total parameter, you don't get the Totals line.

It is also useful for other submissions or finding out how big the novel is.

markdowny count chapters/*.markdown --total | tail -n 1

Synopsis

The summary key is a useful one. I write the chapter synopses as I go. It isn't nearly as overwhelming then trying to write the entire book in a single shot. That means when I have to come up with a chapter-by-chapter synopsis, I can do it fairly easily.

markdowny sections chapters/*.markdown > synopsis.markdown

The above command line goes through all of the chapter files, pulls out the title and summary block and creates a new Markdown file that contains all the summaries.

# Rutejìmo

Rutejìmo was on top of the clan's shrine roof trying to sneak in and
steal his grandfather's ashes. It was a teenage game, but also one to
prove that he was capable of becoming an adult. He ended up falling off
the roof.

The shrine guard, Hyonèku, caught him before he hurt himself. After a
few humiliating comments, he gave Rutejìmo a choice: tell the clan elder
or tell his grandmother. Neither choice was good, but Rutejìmo decided
to tell his grandmother.

# Confession

Rutejìmo returned to his grandmother's cave. He tried to sneak around,
but she caught him entering. When she asked what he had done, he told
her that he had been up at the shrine. His grandmother got upset and
began to berate and beat him, chasing him out of the cave.

Gemènyo interrupted her beating to ask if it was justified. When Tejíko
explained the reason, he agreed but she had lost her anger. As she went
back into the cave, Gemènyo sat down with Rutejìmo and asked
questions. The discussion came to the upcoming rite of passage and how
Rutejìmo would gain magical powers once he experienced it. Gemènyo
wouldn't give details about the rite, but he did tell Rutejìmo that
magic wouldn't change him.

Rutejìmo snapped back, saying that Gemènyo wasn't the greatest warrior
in the clan. Gemènyo didn't seem bothered, but suggested that if
Rutejìmo wanted to be the best, he needed to do something. Rutejìmo
agreed, even knowing he wouldn't.

# Morning

Rutejìmo was sent out to get breakfast for his grandparents. Along the
way to the valley floor, he got distracted by Mapábyo, Hyonèku's adopted
daughter, riding on top of Opōgyo, one of the clan's mechanical dogs
used for dragging heavy loads around. They talk for a short while before
she asked him to come with her to take the load up to her father, who is
at the lookout above the valley entrance.

Even though Hyonèku had caught him the night before, Rutejìmo
agreed. When they get there, Hyonèku started to read a naughty letter
from his wife before Gemènyo interrupted him. Embarrassed, Hyonèku
focused on his daughter while Gemènyo talked with Rutejìmo more.

A little bit of effort ahead of time and I have a chapter-by-chapter breakdown without getting overwhelmed.

Table

The final thing markdowny does is give me that summary table. I use this to compare chapters with each other and try to get an idea of what is going on with the “big picture”.

markdowny table chapters/*.markdown markdowny table -f _basename title _words characters.secondary -t File Title Words:rs "Secondary Characters"

The -f selects the fields inside the YAML. The -t lets me have a pretty name for them. The results happen to be a Markdown table, so it looks a bit prettier if I just show the end results.

Okay, the format is based on the browser, but overall it is somewhat useful. Of course, the early chapters of that book is in the same location. Likewise, I could show the POV (which is useful for some writers) but it doesn't help much since I write single POV novels.

markdowny table chapters/*.markdown -f title _words:r characters.primary purpose

This gives me a decent summary of how long each chapter is, who the main character is, and a list of reasons for that chapter. From there, I have a decent idea of where I need to trim or expand the piece.

Other Tools

I have some other tools. There are ones that take these files and create EPUB, MOBI, and PDF files. I've been using those programs since Sand and Blood was first published. There are others that I've started wht convert the in-world dates (MTR in the above example) into a master timeline or identify every chapter of every novel that happen in a given location.

I also use these chapters to build up the various pages on my Fedran website so patrons can read ahead (that is the availability in the YAML).

Using Markdown

Using Markdown isn't fancy but I find it is easier. Since there is so little control over format, it is easier to focus on the words that need to be written instead of making it pretty.

Also, it is a text file. It plays very well with Git and source control. I don't have to worry about an editor corrupting the file and losing it, it takes up little space, and I can easily switch between Notepad++, Emacs, or Atom without a second thought. I can use the best tool for the job.