About the CyberCat Institute blog
The Cybercat blog website is based on the Whiteglass theme.
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 in locale.
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 asa_b
typeset correctly, while expressions likea_{b}
ora_\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. Fore 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:
- 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 ascalc
,arrows
, etc; and packages such astikz-cd
. Should you needtikz-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 isyyyy-mm-dd-title.md
, create the folderassetsPosts/yyyy-mm-dd-title
- Place your images there
- Reference the images by doing:
![image description](../assetsPosts/yyyy-mm-dd-title/image)
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
CyberCat 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.