This page permanently redirects to gemini://d.moonfire.us/blog/2016/10/31/writing-with-markdown/.

Writing with Markdown and YAML

Four years ago, I wrote a Reddit post[1] 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.

=> 1: https://www.reddit.com/r/writing/comments/un2x9/how_plain_text_editors_became_my_writing_tool_of/

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[2] 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[3] last year).

=> 2: https://www.literatureandlatte.com/scrivener.php | 3: /blog/2015/05/09/gitlab-projects/

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[4]. I use *italics* and **bold** but otherwise not a lot.

=> 4: https://daringfireball.net/projects/markdown/

Front Matter

The really important part is the YAML[5] 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.

=> 5: http://yaml.org/

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

=> 6: https://fedran.com/sand-and-blood/

---
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[7], Perl[8], C#[9]. Most of them have bits and pieces that work, I actually use a combination of all of them.

=> 7: https://github.com/dmoonfire/mfgames-writing-python | 8: https://github.com/dmoonfire/mfgames-writing-perl | 9: https://github.com/dmoonfire/mfgames-writing-cil

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[10] written.

=> 10: https://git.mfgames.com/author-intrusion/markdowny

npm install --global markdowny

## 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.

|------------|--------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------|

| Confession | 2144 | Shimusogo Rutejìmo | Introduce Tejíko, Introduce Gemènyo, Introduce Rutejìmo lack of talent, Introduce style of punishment, Second chapter to get used to names |

Proxy Information

Original URL: gemini://d.moonfire.us/blog/2016/10/31/writing-with-markdown
Status Code: Success (20)
Meta: text/gemini;lang=en-US
Capsule Response Time: 814.219873 milliseconds
Gemini-to-HTML Time: 2.51403 milliseconds

This content has been proxied by September (3851b).