💾 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
⬅️ Previous capture (2022-04-28)
-=-=-=-=-=-=-
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.
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/
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
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}}`.
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]
<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.
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]:
@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`).
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.
To create a new theme, I basically just copy all of the clean theme and start customizing.
Categories:
Tags:
Below are various useful links within this site and to related sites (not all have been converted over to Gemini).
https://d.moonfire.us/blog/2018/08/26/mfgames-writing-themes/