💾 Archived View for d.moonfire.us › blog › 2018 › 08 › 26 › mfgames-writing-themes captured on 2022-04-29 at 12:26:38. Gemini links have been rewritten to link to archived content

View Raw

More Information

⬅️ Previous capture (2022-04-28)

➡️ Next capture (2022-06-03)

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

Theming for MfGames Writing

Up a Level

Previous

Next

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.

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

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

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

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

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

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

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.

Creating New Themes

To create a new theme, I basically just copy all of the clean theme and start customizing.

Metadata

Categories:

Programming

Writing

Tags:

Markdown

MfGames Writing

Footer

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

Contact

Biography

Bibliography

Support

Fiction

Fedran

Coding

The Moonfires

Categories

Tags

Privacy

Colophon

License

Mailing List

https://d.moonfire.us/blog/2018/08/26/mfgames-writing-themes/