💾 Archived View for d.moonfire.us › blog › 2016 › 10 › 31 › writing-with-markdown captured on 2023-05-24 at 18:33:41. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-04-26)
-=-=-=-=-=-=-
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.
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/
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.
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.
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
`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.
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
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.
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.
| Filename | Title | When | Duration | Location | |---------------------|------------|---------------|----------|------------------| | chapter-01.markdown | Rutejìmo | 1471/3/28 MTR | 25 gm | Shimusogo Valley | | chapter-02.markdown | Confession | 1471/3/28 MTR | 35 gm | Shimusogo Valley | | chapter-03.markdown | Morning | 1471/3/29 MTR | 2 m | Shimusogo Valley | | chapter-04.markdown | Rivals | 1471/3/29 MTR | 1 m | Shimusogo Valley | | chapter-05.markdown | Decisions | 1471/3/29 MTR | 3 m | Shimusogo Valley |
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.
| title | _words | characters.primary | purpose | |------------|--------|--------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | Rutejìmo | 1520 | Shimusogo Rutejìmo | Introduce Rutejìmo, Introduce Hyonèku, Introduce naming conventions, Introduce formality rules | | 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 |
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[11] website so patrons[12] can read ahead (that is the `availability` in the YAML).
12: https://fedran.com/patrons/
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.
Categories:
Tags:
Below are various useful links within this site and to related sites (not all have been converted over to Gemini).
https://d.moonfire.us/blog/2016/10/31/writing-with-markdown/