💾 Archived View for d.moonfire.us › blog › 2018 › 08 › 26 › mfgames-writing-themes captured on 2024-08-18 at 21:42:47. Gemini links have been rewritten to link to archived content

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

Theming for MfGames Writing

Up a Level

One of the big parts about MfGames Writing[1] is the ability to customize the appearance of the generated files. If we didn't have that, then every book would look the same and I don't care for that. Books should allow for different themes, chapter numbers, and even spacing. To that regard, everything is funneled through a theme for formatting.

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[5]: Adding front and back matter to novels.

5: /blog/2018/08/23/mfgames-writing-content/

Working with MfGames Writing, CI, and Docker[6]: Adding automatic building with commits.

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

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

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

Theming for MfGames Writing: A light introduction on how to customize the output.
Integrating Semantic Versioning into MfGames Writing[8]: Tying semantic releases into the process.

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

HTML

The entire theme system is built on HTML and CSS. In previous versions of this, I generated XeLaTeX files for PDF and used a custom conversion utility for Word documents. It also increased the complexity significantly. Switching to a HTML-based system simplified the theme creation and made debugging easier.

This is one case where looking at a reference implementation[9] will be helpful.

9: https://gitlab.com/mfgames-writing/mfgames-writing-clean-js

Components

In the content[10] post, there are quite a few references to `element` on each of the content items. These elements are Liquid-based stylesheets that are provided by the theme.

10: /blog/2018/08/23/mfgames-writing-content/

For example, the `title.xhtml` in the clean theme looks like this:

<div class="element-page-break element-page-break-title"> </div>
{{html}}

The `{{html}}` is where the contents in the `source` given on the content will be placed. In this case, the `element-page-break` is how I handle page rendering with WeasyPrint.

A more complicated example would be chapter.xhtml[11]:

11: https://gitlab.com/mfgames-writing/mfgames-writing-clean-js/blob/master/templates/chapter.xhtml

<div class="element-wrapper {{content.element}}">
    <div class="element-page-break element-page-break-right"> </div>
    <div class="element-page-pad-right">
        {% if content.number %}
        <div class="element-number">Chapter {{content.number}}</div>
        {% endif %}
        <h1 class="element-title">{{content.title}}</h1>
        {{html}}
    </div>
</div>

You can see more uses of the Liquid tags. In this case, if we have a `number` property in the content, it will insert the `Chapter #` above the title of the chapter (from the YAML header) and the contents of the body into `{{html}}`.

Recursive Templates

To reduce copy/paste, there are also recursive templates. For example, the colophon[12] template looks like this:

12: https://gitlab.com/mfgames-writing/mfgames-writing-clean-js/blob/master/templates/colophon.xhtml

---
extends: simple-title
---
{{html}}

Once this page is rendered, the results are formatted by the simple-title[13]

13: https://gitlab.com/mfgames-writing/mfgames-writing-clean-js/blob/master/templates/simple-title.xhtml

<div class="element-wrapper {{content.element}}">
<div class="element-page-break element-page-break-right"> </div>
<h1 class="initial">{{content.title}}</h1>
{{html}}
</div>

It is recursive, so you can have one template extending another extending another.

Styling

You'll notice that there is very little styling in the HTML. Instead, most of it is done with a SASS template in the theme. The base style is called stylesheet.scss[14]:

14: https://gitlab.com/mfgames-writing/mfgames-writing-clean-js/blob/master/styles/stylesheet.scss

p {
    margin-bottom: 0;
    margin-top: 0;
    text-align: left;
    text-indent: 2em;
}

Stylesheets can be overridden by specific formats. The most common is having a WeasyPrint-specific stylesheet[15]:

15: https://gitlab.com/mfgames-writing/mfgames-writing-clean-js/blob/master/styles/weasyprint-base.scss

@import "stylesheet";

@page {
    @bottom-center {
        content: counter(page);
        vertical-align: top;
        padding-top: 1em;
    }
    size: letter portrait;
    margin: 3cm 2cm;
}

To figure out overrides, the system looks for the format name first (`html.scss` or `weasyprint.scss`) and if it doesn't find one, goes to the base (`stylesheet.scss`).

Stylesheet Variables

Because I'm fond of single points of truth, SASS also lets us have variables so we can pull the version, or information from the edition data.

@page :right {
    @top-right {
        content: themeString("edition.title");
        vertical-align: bottom;
        padding-bottom: 1em;
    }
    padding-left: 1cm;
}

The `themeString` works just like the Liquid templates.