Jekyll Mahjong Dev Notes

My findings from working on the jekyll-mahjong plugin.

Jekyll Plugin Writing

adding static files to site

Turns out that adding static files like the .svg files to the built site requires some fiddling around. Specifically, if the files didn’t exist before and are added by a Generator plugin during build, the generator must specifically mark those files as static so they can be copied to the built site eventually. What’s more annoying is that if those files already exist before the Generator executes, even if the Generator updates those files, they must not be marked as static files again, otherwise Jekyll complains about duplicate static files. This is why I wrote the copy_as_necessary function in jekyll-mahjong-generator

There is another potential pitfall in updating (overwriting) source files with a generator: the generator will run into an infinite loop if it updates files during re-builds of the site (updated files will then trigger re-builds again). That’s why I added in an @has_run flag to the generator to ensure that it only runs once per jekyll serve.

Scalability V.S. Customization

styling inside SVG?

If we want to allow styling individual tags inside the SVGs through CSS (e.g., to allow customizing the tile designs’ colors), we need to embed the SVG text in the HTML directly. However, doing that is not scalable for jekyll-mahjong, since its usage typically involves displaying the same tile multiple times (we don’t want to embed the same whole SVG multiple times).

In general, if we do want to style inside SVG:

• make sure the embedded SVGs are minimized (e.g., take out unnecessary data like Inkscape metadata)
• make the components selectable either through IDs (for when we are not reusing the component) or through classes:
  • utility to turn each Inkscape label to id here.
  • add classes to components in Inkscape via the XML Editor (hotkey: ctrl + shift + x)

sideways tiles through CSS?

The approach in v2+ to let CSS handle turning the tiles sideways also makes the display more computation-intensive than JUST displaying standalone sideways SVGs. However, this saves us the trouble of having to create and upload two versions of SVGs for every tile design, and also exposes the styling for customization.

Plugin Showcase

See this Riichi Doc.