Top Matter

Typically this is called “front matter” but the problem is that front matter would mean two things.

In publishing, it means the pages before the first chapter like the dedication, table of contents, and pronunciation guides. The appendixes and “about the author” at the end are the—creatively enough—“back matter”.

In writing files, front matter is a block of text at the top of a file that gives details about the file.

To make things easier for me, who doesn't like the same phrase meaning two different things, I'm going to call it “top matter” because it is at the top of the file.

Format

Different tools identify front matter in different ways. My explainations are going to be the method that MfGames Writing uses which is also what most of my tools use.

The basic format of the top matter looks like this:

---
title: Name of the Chapter
---

It was a dark and stormy night.

The --- at the top of and bottom identify the matter for the file. Everything inside it is a YAML block that describes the details.

For the most part, YAML isn't that hard to start with. It is basically a key/value pair with a : between them. In the above example, the title of the chapter (title: ) is “Name of the Chapter”.

Other Values

By itself, just having a title isn't that interesting. Where matter becomes useful is that it can be used for additional pieces of information.

For example, in a multiple POV novel, having a pov: entry makes it easier to query the chapters to list the chapters from a given POV or give a hint of which point of view the chapter should be written in.

---
title: Chapter One
pov: Bob
---

I frequently use the chapters to have the date the chapter happened, time of day, and location.

---
title: Chapter One
when: Friday
where: The Old Bar
---

You could also use it to tag the scene and sequels if you follow Dwight V Swain's techniques.

---
title: Chapter One
when: Friday
where: The Old Bar
type: sequel
---

An Extensive Example

The front matter for the first chapter of Sand and Blood shows a much larger set of information:

---
availability: public
when:
  start: 1471/3/28 MTR 4::22
  duration: 0::30
date: 2012-02-18
title: Rutejìmo
locations:
  primary:
    - Shimusogo Valley
characters:
  primary:
    - Rutejìmo
  secondary:
    - Hyonèku
  referenced:
    - Ganóshyo (Epigraph)
    - Gemènyo
    - Chimípu
    - Yutsupazéso
    - Tejíko
organizations:
  secondary:
    - Shimusògo
concepts:
  referenced:
    - The Wait in the Valleys (Epigraph)
warnings:
  primary:
    - Bullying
    - Violence
    - Verbal Abuse
    - Physical Assault
  secondary:
    - Named Character Death
    - Unnamed Animal Death
purpose:
  - Introduce Rutejìmo
  - Introduce Hyonèku
  - Introduce naming conventions
  - Introduce formality rules
  - Introduce the basic rules of politeness
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.
---