💾 Archived View for d.moonfire.us › blog › 2018 › 08 › 23 › mfgames-writing-content captured on 2024-07-09 at 02:19:46. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Adding Content to MfGames Writing

Up a Level

In my continuing introduction to MfGames Writing[1], I've only given a very brief introduction to adding content to the publication. Like everything else, there is a lot more complexity in the process to support various components of a novel: bastard and full titles, table of contents, appendixes, and even colophons.

1: /tags/mfgames-writing/

Series

I appear to be writing a short series of post about the tools I use for publication and writing.

Semantic Versions and Releases[2]: Why semantic versioning helps with the writing process.

2: /blog/2018/08/13/publishing-processes/

Evolution of MfGames Writing[3]: A brief history and reasoning behind the tools.

3: /blog/2018/08/21/mfgames-writing-reasons/

First Steps Using MfGames Writing[4]: Starting a new project with MfGames Writing.

4: /blog/2018/08/22/mfgames-writing-init/

Adding Content to MfGames Writing: Adding front and back matter to novels.
Working with MfGames Writing, CI, and Docker[5]: Adding automatic building with commits.

5: /blog/2018/08/24/mfgames-writing-docker-and-ci/

Additional Formats for MfGames Writing[6]: How to create PDF, MOBI, DOCX, and HTML versions.

6: /blog/2018/08/25/mfgames-writing-formats/

Theming for MfGames Writing[7]: A light introduction on how to customize the output.

7: /blog/2018/08/26/mfgames-writing-themes/

Integrating Semantic Versioning into MfGames Writing[8]: Tying semantic releases into the process.

8: /blog/2018/08/27/mfgames-writing-releases/

More Than Chapters

In the previous[9] blog post, I gave a short example of `publication.yaml` that included all the chapters in a folder.

9: /blog/2018/08/22/mfgames-writing-init/

contents:
    - element: chapter
      number: 1
      directory: chapters
      source: /^chapter-\d+.md$/
      start: true
      page: 1

This would include any number of chapters, from `01` to `99`.

Covers

Most EPUB files need a good graphical image for readers. Creating MOBI (via `kindlegen`) from the EPUB also requires a graphical image. Adding one is pretty easy.

- element: cover
  source: build/repos/fedran-covers/dist/full/0100-00-sand-and-blood-front.jpg
  linear: false
  exclude:
      editions: [pdf]
      toc: true

The `element` is the name of the component in the theme[10]. Basically that determines how it is rendered when we generate the files.

10: /blog/2018/08/26/mfgames-writing-themes/

The `source` is the relative path to the image. It should be a JPEG image. In my example, I have it pulling from another Git repository but it can be a file checked into the Git. In general, it needs to be a file that will be accessed while building.

We use `linear: false` because covers are one of those things that reader software will occasionally rearrange. In other words, I don't know, it seems to be required.

We also use `exclude:` to exclude it from the table of contents (`toc`) and from the PDF version[11].

11: /blog/2018/08/25/mfgames-writing-formats/

Titles

- element: bastard
  source: frontmatter/bastard.html
  linear: false
  exclude:
      editions: [epub]
      toc: true
- element: title
  source: frontmatter/title.html
  linear: false
  exclude:
      toc: true

In this case, we are using the `bastard` and `title` templates (nearly identical) from the theme. I put my front matter files in a directory creatively called `frontmatter`. You can probably guess where the back matter goes. I could use a number in the front (like chapters) and a pattern but I like to be explicit with my matters.

The `exclude.toc` is because title pages don't show up in the table of contents.

Legal Page

- element: legal
  source: frontmatter/legal.markdown
  liquid: true
  linear: false

The legal page introduces a new concept. The `liquid` flag lets me use Liquid templates on the page. The variables available for the tags are combined from three places: the `package.json` file, the `metadata` section in `publication.yaml`, and then the edition being generated from the same file. This means you can store variables like the version from `package.json` but an ISBN from the edition.

Since we are using Liquid, we can also have some simple logic such as the optional ISBN which only shows up in the `pdf` edition. This would allow us to have two different versions of the book (say hardcover and paperback) with different formats and edition names.

---
title: Legal
---

Broken Typewriter Press\
[https://broken.typewriter.press/](https://broken.typewriter.press/)

{% if edition.isbn %}
ISBN {{ edition.isbn }}
{% endif %}

Version {{ edition.version }}

Using versions like this could also be used to create site-specific buy links for the different editions (such as a Amazon or Smashwords-specific edition of the same file).

The table of contents (`element: toc`) has a special code to generate one if a source isn't given. However, the generated code doesn't do page numbers which is why I currently have it turned off in PDF. For EPUB and MOBI, it will generated a properly linked table for each chapter.

- element: toc
  linear: false
  title: Contents
  exclude:
      editions: [pdf]

Pipelines

The last interesting component to point out is the pipelines. A pipeline is something that modifies the original Markdown before it is converted into HTML (I've needed a post conversion one also but I haven't coded it). These are used to handle word hyphenation (we don't do it by default), either for generic languages or for specific languages (such as the Fedran one to handle Miwāfu[12] names). There is also one[13] to convert `<<` and `>>` into `«` and `»` (I use this for telepathy in my books).

12: https://fedran.com/miwafu/

13: https://www.npmjs.com/package/@mfgames-writing/guillemet

- element: chapter
  number: 1
  directory: chapters
  source: /^chapter-\d+.markdown$/
  start: true
  page: 1
  pipeline: &pipelines
      - module: "@fedran/writing-hyphen"
      - module: mfgames-writing-hyphen

Sand and Blood example

Using Sand and Blood[14] as an example:

14: https://gitlab.com/fedran/sand-and-blood/blob/master/publication.yaml

contents:
    - element: cover
      source: build/repos/fedran-covers/dist/full/0100-00-sand-and-blood-front.jpg
      linear: false
      exclude:
          editions: [pdf]
          toc: true
    - element: bastard
      source: frontmatter/bastard.html
      linear: false
      exclude:
          editions: [epub]
          toc: true
    - element: title
      source: frontmatter/title.html
      linear: false
      exclude:
          toc: true
    - element: legal
      source: frontmatter/legal.markdown
      liquid: true
      linear: false
    - element: dedication
      source: frontmatter/dedication.markdown
      linear: false
    - element: toc
      linear: false
      title: Contents
      exclude:
          editions: [pdf]
    - element: preface
      source: frontmatter/miwafu.html
      linear: false
    - element: chapter
      number: 1
      directory: chapters
      source: /^chapter-\d+.markdown$/
      start: true
      page: 1
      pipeline: &pipelines
          - module: "@fedran/writing-hyphen"
          - module: "@mfgames-writing/hyphen"
    - element: appendix
      source: backmatter/about.markdown
    - element: appendix
      source: backmatter/fedran.markdown
    - element: appendix
      id: license
      source: backmatter/license.markdown
    - element: appendix
      source: backmatter/patrons.markdown
    - element: appendix
      source: backmatter/credits.markdown
    - element: colophon
      source: backmatter/colophon.markdown

EPUBCHECK

Once you get the basics in (cover, table of contents, and chapters), the resulting EPUB file will easily get through `epubcheck` which makes it easier to then convert that into a MOBI file using `kindlegen`.