Directories

One of the difficulties I found over the years is finding a consistent format for my project, both writing and coding. I've written up a plot of how I organize my projects[1]. There are a lot more details in that link, but I'll give a quick summary of them. You may consider reading the conventions[2] page because it will explain some of the notation.

Many of these decisions are because I also use tools to process my files. If the files are in the same place, every time, then I don't have to write custom logic[3] to handle those tools. I always know that `markdowny-wc src/chapters/*.md` works, no matter which project I'm in. It also means I can drop in a configuration file across all of my repositories and know it will work.

Read Me

Most forges[4] have support for showing the `README.md` file in any directory. The root level one, `//README.md` shows up on the front page as a general description of the project. I typically put high-level details in here:

• The title of the project
• The author since I have used bylines or format books for other folks
• Copyright
• ISBN numbers
• The blurb/summary
• The elevator pitch
• Store links
• The inspiration for the project

Over the years, I used to try putting `README.md` files in other places but they didn't really give any benefit besides spending time, so I stopped doing it.

License

Even when I don't intend to put a writing project in a public repository, I usually add a `LICENSE.md` file. Since most of my writing is Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International [5], I use the Markdown version of the license and put it there.

If the project isn't shared, an “All rights reserved.” should be sufficient.

Tasks

As I'm going through the project, occasionally I realize I need to do something but I don't want to lose my flow. To make sure I don't forget it (again), I throw everything into a `//TASKS.md` file. Usually this is just a bullet list but it is good since I can switch to that file, type, save, close, and get back without losing too much momentum.

My task files usually look this this:

---
title: Tasks
---

- Look for overuses of nodding
- Go through and check Brook's hair color

It isn't really fancy. Though, I keep wanting to make this a check list (in Markdown, this is a `- [ ] Look for overuses of nodding`) but that implies I want to keep the tasks I finished. In most cases, once I go back and finish it, I delete the line so an empty tasks file is a happy file.

Chapters

The main “source” of the project are the actual words. I treat all of them as chapters with short stories simply being single chapter novels. This means I have a consistent naming convention to identify the files which lets me use muscle memory or boilerplate processes to generate.

Creatively enough, I put these under the `//src/chapters/` folder with each chapter being `chapter-XXX.md` with the `XXX` starting at `001` and incrementing one for each successive chapter. That means chapter eight is `//src/chapters/chapter-008.md`.

The reason I zero-padded the number is because the zero-padding ensures that the chapters are always alphabetical when I list files or view them in a file explorer. While `chapter-5.md` and `chapter-10.md` will sort correctly in some explorers, such as later Microsoft Windows file explorers, automated tools are rarely that intelligent and will provide it in lexical order which means `chapter-10.md` will come before `chapter-5.md`. The zero padding ensures that everything sorts it correctly.

The three digits is because I have written series that have had more than a hundred chapters. Having the consistent naming means my scripts don't have to be aware of one, two, or three-digit chapters which results is simpler and easier to maintain code.

I don't put the title in the file name because I found that it changes too often. However, others might find putting `001-enter-the-kitty-gunslinger.md` would also work just as easily as a simple `chapter-001.md`.

Removed Chapters

Occasionally, I'll write a chapter and realize it doesn't make sense anymore. But I don't want them in the `chapters` folder, so I move them `//src/removed/` folder and rename them to give a bit more context and change `chapter` to `removed`. For example, I might move `chapter-004.md` to `removed-lily-wanders-her-stash.md`.

The reason I do this is because I use “fuzzy find” a lot while I work. And I jump between chapters with `Control-P 002 ENTER` so I don't want any other “002” files because it slows me down. I want a full chapter number to find only a single file. But having the `removed-` at the beginning helps when I'm doing a more generic search, such as `Control-P lily`, and know which file is which.

Matter

An important part of the publication process is producing front and back matter[6]. This includes things like fancy and bastard title pages, about the author appendixes, “see also”, and even simple things like dedications. They aren't really chapters per-se, but still important.

I group all of these into the `//src/matter/` directory. Some example:

• `title.html` is usually the title page and is usually straight-up HTML
• `bastard.html` is the bastard version of the title
• `legal.md` contains the legal information page including copyright
• `dedication.md` is the book's dedication, if I have one
• `author.md` is the “about the author” section

Title Pages

The title pages are HTML instead of Markdown. I use CSS to style them because usually they need some additional attention and are rather book-specific.

Data

I like to check information about characters, snippets of descriptions, or general notes as I go. These are usually a directory of free-free form files with cross-linking between them. The most common is one file per major character. For example:

• `//src/data/linsan.md` contains information about Linsan, the main character of a novel

I might group these data files according to something that makes sense.

• `//src/data/shimusogo/gemenyo.md` which gathers all the Shimusògo clan members in one place.

There are many reasons I do this.

The first is that most of these notes are snippets, removed phrases, or things about the character for that book. They don't really make sense to add to a wiki or more formalize the content. They are usually written with very little formatting but are useful for keeping consistent. I'll put things like eye colors, favorites form of dress, catch phrases, and even the first few times I describe the characters.

The second reason is that they are checked in. Which means they are control by source[7] and if I make a change, I can see the previous version.

The third is they are part of the project. When I using something like Visual Studio Code[8], I edit the project root so I can use “Find in Files” to find all information, even ones in notes. A search and replace works across them so everything is kept up to date. It also means I can easily `Control-P name-of-character ENTER` to jump to that file without every taking my hands off the keyboard.

Finally, the fourth is that I have started to write various tools that use the data directory as a “lookup” of sorts. The intent is that it gives me a consistent location so I can `Shift-F1` and see a little popup that gives a summary of the character. That isn't really ready for prime time, but it is cool to be able to click on a name and ask for a reminder of those character details.

Footer

Below are various useful links within this site and to related sites (not all have been converted over to Gemini).