Peter Gao

I am a code writer, machine teacher, manga reader, video gamer, and a graphic design dilettante. Also, I run a Japanese Mahjong club.

jekyll-mahjong adds a mahjong Liquid tag that converts any input text mahjong notation into .svg tile images.

Links: GitHub and RubyGems

Setup

Installation

First, add gem "jekyll-mahjong" to the :jekyll_plugins group in your Gemfile and run bundle install.

group :jekyll_plugins do
  gem "jekyll-mahjong"
end

Then, you need to ensure that Jekyll sees the stylesheet /_sass/mahjong.scss. For many Jekyll themes, this just means adding the following line to your site source’s /assets/css/main.scss:

@import "mahjong";

After installing the plugin and building your site once, you’ll find /assets/tiles/*.svg and /_sass/mahjong.scss in your site’s source directory. If you want, you can add them to your .gitignore. If you already have those files in your source directory, jekyll-mahjong won’t overwrite them unless you specifically enable overwriting (see next section).

Customization

All styling is done through /_sass/mahjong.scss; you can modify it to adjust parameters like the height of tiles, space between tile groups, etc.

Similarly, you can replace the /assets/tiles/*.svg files with your own tile SVGs; just make sure that you follow the existing filenames.

Finally, if you want jekyll-mahjong to overwrite those files with the built-in version every time you build your site (e.g., for updating the built-in version) In your _config.yml, you can add the following lines:

jekyll-mahjong:
  overwrite_SCSS: true # default: false
  overwrite_tiles: true # default: false

Usage

Quick Example

{% mahjong 111m456p8p134s 4p 7z7Z7z %}

1m1m1m4p5p6p8p1s3s4s4p7z7Z7z

As demonstrated, we can use one mahjong tag to render multiple groups of mahjong tiles, both in upright and sideways position. The example came from this WWYD problem.

Notation / Parsing

Suits

The letters mspz denote “manzu 2m, souzu 2s, pinzu 2p, honor 2z” suits respectively.

Lower-case letters are for upright tiles, and upper-case letters are for sideways tiles. 123s123S => 1s2s3s1S2S3S

Numbers

The numbers correspond to the number of the tile. Note:

  • 0m0s0p are red fives: 0m0s0p
  • 1234567z are honor tiles in this order: 1z2z3z4z5z6z7z
  • you only need to specify the suit once for adjacent tiles of the same suit (e.g., 12m34p5m instead of 1m2m3p4p5m to display 1m2m3p4p5m

Extra Tiles

The suit x is for “extra” tiles. Currently available tiles: 1x1X => 1x1X

Multiple Groups

If you want to display multiple groups of tiles (as one hand), you can leave a space between groups:

{% mahjong 3z 1x11z1x 1x22z1x 1x44z1x 1x66z1x %}

3z1x1z1z1x1x2z2z1x1x4z4z1x1x6z6z1x

Styling Choices

A negative right margin ($negative_right_margin in mahjong.scss) is included to reduce the amount of outline shown between two tiles in the same group/hand.

3s3s3s4s (with negative right margin)

3s3s3s4s (without negative right margin)

The space between two groups of tiles is governed by $tile_group_space_width.

Edge Cases

Here are some edge cases to demonstrate the plugin’s robustness.

tiles in heading: 1x3s1x

The tiles are <img> tags. They can be displayed in the heading but they won’t show up in Minimal Mistakes’ table of contents.

empty tags

BEFORE{% mahjong %}AFTER

BEFOREAFTER

mixed invalid and valid notation

BEFORE{% mahjong sdnj 12p sdfjnj 406s asdkfj %}AFTER

BEFORE1p2p4s0s6sAFTER

Credits

Code Author

Peter Gao

Uzaku Tile SVGs

Face-up Tile SVGs are originally from this Font. I ripped and reorganized the SVGs.

Updated: