Programming Guide

Notes for Programmers

This wiki is powered by Jekyll, a static site generator. The templating language is Liquid. Jekyll has provided additional Liquid filters and tags to make life easier.

I swear to god that Jekyll/Liquid’s documentation is a lot easier to understand than SemanticWiki’s documentation, so please read.

For code change that affects significant parts of the website (excluding trivial bug fixes), please open a new Pull Request instead of directly commiting to the master branch.

For code change related to website design, please include screenshot preview whenever possible.

Code convention

You can use any modern HTML/CSS/JS features you like. Bootstrap and JQuery are banned, other dependencies can be considered.

We do most of the content processing and rendering in Jekyll/Liquid so that the content is ready as soon as web browser downloads a page. However, if certain feature is too difficult to implement in Jekyll/Liquid or it is not neccessary to load as soon as possible, it is good to embed some information as data-* attribute in some HTML elements and do more processing in client-side JS. Think: progressive enhancement.

Random things about Jekyll/Liquid templating

  1. To enumerate all objects in a map/dictionary (e.g. {"a": 1, "b": b}), do this:

    {% for pair in obj_map %}
{{ pair[0] }} is key, {{ pair[1] }} is value
{% endfor %}

  2. To access parameters passed to a template, use include.varname. Example:

    # Somewhere in a .md file
{% include awesome-tmpl.html username="Alex" %}

    # In `_includes/awesome-tmpl.html`
Username: {{ include.username }}

  3. Comment syntax in Jekyll/Liquid is {% comment %}blah blah{% endcomment %}.

  4. Key of map/dictionary is type sensitive. {1: "hello", 2: "world"} uses integer as key. {"1": "hello", "2": "world"} string as key. Make sure you the key is in correct type when you do {% assign value = obj_map[key] %}.

  5. To convert string into integer, use {% assign x_int = x_str | plus: 0 %}.

  6. To convert integer into string, use {% assign x_str = x_int | downcase %}.

  7. You cannot re-assign to variable used in the for loop enumeration, in another words this is not allowed:

    {% for flower in flowers %}
{% assign flower = flower | upcase %} # `flower` still won't be changed
{% endfor %}

    Instead create a new variable:

    {% for flower in flowers %}
{% assign f = flower | upcase %}
{% endfor %}