💾 Archived View for d.moonfire.us › blog › 2018 › 08 › 22 › mfgames-writing-init captured on 2024-08-18 at 21:41:50. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2023-04-26)
-=-=-=-=-=-=-
Getting started with MfGames Writing[1] can be a bit overwhelming. This is the beginning of how to get started. These directions are mainly focused toward technical users who already have a basic skill in Git.
I appear to be writing a short series of post about the tools I use for publication and writing.
2: /blog/2018/08/13/publishing-processes/
3: /blog/2018/08/21/mfgames-writing-reasons/
4: /blog/2018/08/23/mfgames-writing-content/
5: /blog/2018/08/24/mfgames-writing-docker-and-ci/
6: /blog/2018/08/25/mfgames-writing-formats/
7: /blog/2018/08/26/mfgames-writing-themes/
8: /blog/2018/08/27/mfgames-writing-releases/
I always start by creating a new Git project on GitLab[9]. You can do the same with GitHub, BitBucket, or just locally. Since I'm focusing on the tools, I'm going to assume you know how to create those projects.
$ git checkout https://oauth2:SecretPassword@gitlab.com/dmoonfire/test-project.git ... stuff happens $ cd test-project
You could create a new folder, it doens't really matter.
$ mkdir test-project $ cd test-project $ git init
The way builds work, there are quite a few files that will be generated that wouldn't be checked into the repository. This is one thing that makes NPM so powerful. To avoid that, we create a `.gitignore` file that ignores those files.
# Emacs and VI creates these files and I'm too lazy to turn it off.
EditorConfig[10] is a tool for providing some consistency in formatting. For novels, it doesn't make sense but I like to have it there to make sure the supporting files are consistent. This is an optional file, I just like having it.
# EditorConfig is awesome: http://EditorConfig.org
# top-most EditorConfig file
root = true
[*]
charset = utf-8
end_of_line = lf
indent_brace_style = K&R
indent_size = 4
indent_style = space
insert_final_newline = true
max_line_length = 80
tab_width = 4
trim_trailing_whitespace = true
curly_bracket_next_line = false
[*.{js,ts}]
quote_type = double
[*.yaml]
indent_size = 2
tab_width = 2
[package.json]
indent_size = 2
tab_width = 2
The versioning and management comes from `package.json`. This is the file that says which version of which utilities to use. Now, you can use `npm init` to figure it out but this is the basic file.
{
"name": "test-project",
"private": true,
"version": "0.0.0"
}
There is other stuff, but these are the key parts. The name is the slug of the file. For me, it is always the name of the folder in the website and the Git repository. I also use this to build my website, so it is a pretty consistent format. You can call it whatever you want and change it as you need.
The `private` is to prevent you from accidently publishing your novel on NPM[11].
Finally the `version` is used for the semantic release[12] and populates data on the legal page of the resulting book. In general, I start with “0.0.0” and then bump it to “1.0.0” when I finalize the book and publish it for the first time.
12: /blog/2018/08/13/publishing-processes/
Now, we need somethig to put into the story or novel. Since I've started this, I organize even my short story into chapters. To do that, you can put it anywhere, but I always put my chapters in (unoriginally) the `chapters/` folder. I also use two-digit numbers with zero padding so it sorts correctly (this is useful). You can see this at Sand and Blood's Git Repository[13].
13: https://gitlab.com/fedran/sand-and-blood/
For example, `chapters/chapter-01.md`:
--- title: Mistakes Were Made --- It was a bright and terribly sunny day. I didn't like it.
Because of the flexibility (if you don't want to use `chapters/`, want to spread it out across deeper folders), nothing is automatic when it comes to formatting the books. To control it, we have a simple file called `publication.yaml` which tells the system how to create the output. This would go at the top-level file.
metadata:
title: Test Project
author: D. Moonfire
language: en
theme: "@mfgames-writing/clean"
outputDirectory: .
outputFilename: test-project-{{edition.version}}.{{edition.editionName}}
editions:
epub: # This is the edition.editionName.
format: "@mfgames-writing/epub2"
contents:
- element: chapter
number: 1
directory: chapters
source: /^chapter-\d+.md$/
start: true
page: 1
Now, since this file is the core of MfGames Writing, it needs a bunch of details.
Many of the fields use Liquid[14] templates. That is the stuff between `{{` and `}}`. The main reason we use it is so we can simplify some of our logic. For example, instead of putting `outputFilename` in every edition, we can use variables to fill it in. Also, we can substitute `{{ edition.version }}`` to have the version from the `package.json`file. The`{{edition.editionName}}`will have`epub`for the`epub:`line. This means it wil produce a file`test-project-0.0.0.epub` when it runs.
14: https://shopify.github.io/liquid/
The formatting is driven around the idea of a “theme”. Right now, there are only three themes. Two are private or require custom fonts, the other is @mfgames-writing/clean[15] which is a utilitarian theme based on SASS and some templates. These themes are used to create a consistent style. I also have more specialized themes:
15: https://www.npmjs.com/package/@mfgames-writing/clean
16: https://www.npmjs.com/package/@fedran/writing-theme/
17: https://www.npmjs.com/package/@typewriter-press/efferding-writing-theme
18: https://typewriter.press/randy-roeder/sins-of-intent/
Both of these have custom fonts (Corda and Mr. Eaves) with a bit of logic. I could easily see this being expanded by anyone to create a gallery of formatting for books. Right now, I'm focusing on these three because they are functional enough.
See the later post on theme specifics.
Editions are basically versions of the output. For Sand and Blood, I have one for EPUB, HTML, and PDF. MOBI and DOCX are generated from those three sources. You can have any number of editions, different file names, different output directories, even different variables like ISBN numbers.
Content is what goes into the file. Right now, we only have a single element, all the files in the chapter folder.
- element: chapter number: 1 directory: chapters source: /^chapter-\d+.md$/ start: true page: 1
The `element` tells the theme how to format it. Later examples will include more but you can have things like `preface` or `appendix` or titles and the like.
The `number` property basically is used if you want to have “Chapter 1” in the theme but with a custom title. If your chapter is just “One”, “Two”, “Three”, you wouldn't define this. My books do since I use chapter titles.
The `directory` and `source` work together to figure out which files are to be included.
`start` is used by EPUB and MOBI to figure out where to automatically navigate when the reader first goes into the page.
Finally `page` is used by the PDF system to restart page numbering. Usually this would be left blank.
At this point, I have a minimum novel project. Time to make it actually produce something. Like in the previous[19], everything is self-contained in the directory. We use `npm` to install the packages needed to build the project.
19: /blog/2018/08/21/mfgames-writing-reasons/
$ npm install @mfgames-writing/format @mfgames-writing/clean @mfgames-writing/epub2
The `@mfgames-writing/format` provides the command-line tools and does the work. There is also the “clean” theme and a third for the output (EPUB2).
Once these install, running the output should work with the following command.
$ npx mfgames-writing-format build ... lots of colorful output $ ls *.epub test-project-0.0.0.epub
If all goes well, you'll see `test-project-0.0.0.epub` in the root directory. It won't pass `epubcheck` check (we are missing a few things), but this is the basics of the publishing system.
Categories:
Tags:
Below are various useful links within this site and to related sites (not all have been converted over to Gemini).