About the QSig Commission blog

Fabrizio Genovese · June 4, 2024

jekyll   update
The space at the beginning of each post is used for acknowledgements.

QSig Commission logo

The QSig Commission blog website is based on the Reverie theme by Amit Merchant.

TOC

Workflow

Standard github workflow:

  • Clone this repo
  • Create a branch
  • Write your post
  • Make a PR
  • Wait for approval

The blog will be automatically rebuilt once your PR is merged.

Previewing

Since the blog uses Jekyll, you will need to install it or use the included nix flake devshell (just run nix develop with flakes-enabled nix installed) to be able to preview your contents. Once the installation is complete, just navigate to the repo folder and give bundle exec jekyll serve. Jekyll will spawn a local server (usually at 127.0.0.1:4000) that will allow you to see the blog locally.

Post preamble

Posts must be placed in the _posts folder. Post titles follow the convention yyyy-mm-dd-title.md. Post assets (such as images) go in the folder assetsPost, where you should create a folder with the same name of the post.

Each post should start with the following preamble:

---
layout: post
title: the title of your post
author: your name
categories: keyword or a list of keywords [keyword1, keyword2, keyword3]
excerpt: A short summary of your post
image: assetsPosts/yourPostFolder/imageToBeUsedAsThumbnails.png This is optional, but useful if e.g. you share the post on Twitter.
usemathjax: true (omit this line if you don't need to typeset math)
thanks: A short acknowledged message. It will be shown immediately above the content of your post.
---

As for the content of the post, it should be typeset in markdown.

Latex

  • Inline math is shown by using $ ... $. Notice that some expressions such as a_b typeset correctly, while expressions like a_{b} or a_\command sometimes do not. I guess this is because mathjax expects _ to be followed by a literal.
  • Display math is shown by using $$ ... $$. The problem above doesn’t show up in this case, but you gotta be careful: 
      text
  $$ ... $$
  text

    does not typeset correctly, whereas:

      text

  $$
  ...
  $$

  text

    does. You can also use environments, as in:

      $$
  \begin{align*}
   ...
  \end{align*}
  $$

Theorem environments

We provide the following theorem environments: Definition, Proposition, Lemma, Theorem and Corollary. Numbering is automatic. If you need others, just ask. The way these works is as follows:


{% def %}
A *definition* is a blabla, such that: $...$. Furthermore, it is:

$$
...
$$

{% enddef %}

This gets rendered as follows:

A definition is a blabla, such that: $…$. Furthermore, it is:

\[...\]

Numbering is automatic. Use the tags:


{% def %}
    For your definitions
{% enddef %}

{% not %}
    For your notations
{% endnot %}

{% ex %}
    For your examples
{% endex %}

{% diag %}
    For your diagrams
{% enddiag %}

{% prop %}
    For your propositions
{% endprop %}

{% lem %}
    For your lemmas
{% endlem %}

{% thm %}
    For your theorems
{% endthm %}

{% cor %}
    For your corollaries
{% endcor %}

Referencing

If you need to reference results just append a {"id":"your_reference_tag"} after the tag, where your_reference_tag is the same as a LaTex label. For example:


{% def {"id":"your_reference_tag"} %}
A *definition* is a blabla, such that: $...$. Furthermore, it is:

$$
...
$$
{% enddef %}

Then you can reference this by doing:

As we remarked in [Reference description](#your_reference_tag), we are awesome...

Typesetting diagrams

We support two types of diagrams: quiver and TikZ.

Quiver

You can render quiver diagrams by enclosing quiver expoted iframes between quiver tags:

  • On quiver, click on Export: Embed code
  • Copy the code
  • In the blog, put it between delimiters as follows:

{% quiver %}
<!-- https://q.uiver.app/codecodecode-->
<iframe codecodecode></iframe>
{% endquiver %}

They get rendered as follows:

Should the picture come out cropped, select fixed size when exporting the quiver diagram, and choose some suitable parameters.

Tikz

You can render tikz diagrams by enclosing tikz code between tikz tags, as follows:


{% tikz %}
  \begin{tikzpicture}
    \draw (0,0) circle (1in);
  \end{tikzpicture}
{% endtikz %}

Tikz renders as follows:

Notice that at the moment tikz rendering:

  • Is not rendered on some browsers like Safari, unfortunately. This is a total bummer but there isn’t much we can do about it. So refrain from using this unless strictly necessary.
  • Supports any option you put after \begin{document} in a .tex file. So you can use this to include any stuff you’d typeset with LaTex (but we STRONGLY advise against it).
  • Does not support usage of anything that should go in the LaTex preamble, that is, before \begin{document}. This includes exernal tikz libraries such as calc, arrows, etc; and packages such as tikz-cd. Should you need tikz-cd, use quiver as explained above. If you need fancier stuff, you’ll have to render the tikz diagrams by yourself and import them as images (see below).

Referencing

Referencing works also for the quiver and tikz tags, as in:


{% tikz {"id":"your_reference_tag"} %}
...
{% endtikz %}

This automatically creates a numbered ‘Figure’ caption under the figure, as in:

Whenever possible, we encourage you to enclose diagrams into definitions/propositions/etc should you need to reference them.

Images

Images are included via standard markdown syntax:

![image description](image_path)

image_path can be a remote link. Should you need to upload images to this blog post, do as follows:

  • Create a folder in assetsPosts with the same title of the blog post file. So if the blogpost file is yyyy-mm-dd-title.md, create the folder assetsPosts/yyyy-mm-dd-title
  • Place your images there
  • Reference the images by doing: 
      ![image description](../assetsPosts/yyyy-mm-dd-title/image)

If the name of the post changes, you should also change the name of the image folder. This will force you to change also the relative paths of all the images links. To avoid this, just specify

asset_path: /assetsPosts/yyyy-mm-dd-title/

in the post preamble, and reference images by giving


![image description]({{page.asset_path}}/image)

In this way, changing asset_path will be enough, and you won’t have to correct all the image references.

Whenever possible, we recommend the images to be in the format .png, and to be 800 pixels in width, with transparent backround. Ideally, these should be easily readable on the light gray background of the blog website. You can strive from these guidelines if you have no alternative, but our definition and your definition of ‘I had no alternative’ may be different, and we may complain.

Referencing

Referencing works exactly as for diagrams:


{% figure {"id":"your_reference_tag"} %}
  ![image description](image_path)
{% endfigure %}

Code

The QSig blog offers support for code snippets:

def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.

To include a code snippet, just give:

```language the snippet is written in
your code
```

Check out the Jekyll docs for more info on how to get the most out of Jekyll. File all bugs/feature requests at Jekyll’s GitHub repo. If you have questions, you can ask them on Jekyll Talk.

Cross-posting

If you want to cross-post from another blog, just add this to the post preamble:

crosspostURL: "https://example.com"
crosspostName: "Some text"

This will display the following banner at the very beginning of the post:

This is a cross-post from some text.

Twitter, Facebook