Contributing to the NeverLocal blog

Fabrizio Genovese and Stefano Gogioso · June 4, 2024

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

NeverLocal logo

The NeverLocal blog is based on the Reverie Jekyll theme by Amit Merchant. The blog is open to external contributors, and this post details the workflow and available features for all contributions.

Table of Contents

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.

Local Preview

For local preview, you will need to install Jekyll. Once the installation is complete, navigate to the root folder of the repository and run the following command once to install its dependencies:

bundle install

Now, everything is set up. To preview the blog, run the following command:

bundle exec jekyll serve --incremental

Jekyll will spawn a local server at 127.0.0.1:4000: navigate to that address in a browser to see preview the blog locally. If you encounter issues and need detailed debugging information, run the following command instead:

bundle exec jekyll serve --incremental --trace --verbose

Local Preview (Nix)

If you have the flakes-enabled nix package manager installed, you can instead use the nix flake devshell included in this repository to preview the blog contents:

nix develop

Post and Asset Locations

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 a sub-folder assetPost/yyyy-mm-dd-title of the assetsPost folder named exactly as the post file (without the .md extension). For example, if your post file is in _posts/2024-06-11-zx-intro.md, the corresponding assets go into assetPost/2024-06-11-zx-intro.

Front Matter

Each post should start with the following YAML front matter:

---
layout: post
title: the title of your post
author: your name(s)
categories: keyword or a list of keywords [keyword1, keyword2, keyword3]. Use quotes "" for multi-word keywords.
excerpt: A short summary of your post
image: assetsPosts/yyyy-mm-dd-title/imageToBeUsedAsThumbnails.png (optional, but useful if e.g. you share the post on social media)
usemathjax: true (set to false if you don't typeset math)
thanks: An optional short acknowledgement message. It will be shown immediately above the content of your post.
---

Post Contents

The remainder of the post should be written in Markdown. The following sections present available features.

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 NeverLocal 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