My digital copybook

This is my web book! Gianluca Casati writes here :)

Domain

The domain for this site is g14n.info registered on namecheap; thanks to CloudFlare it is a naked domain and has SSL: both http and https schemes are available. However, the default scheme I prefer when linking my site and articles is http.

Style

Yes! Jekyll supports Sass, I am using a style.scss that imports partials and it is integrated on GitHub Pages, read

• Using Sass with Jekyll
• Assets doc page on Jekyll website

A really good starting point is the Jekyll scaffold you obtain launching

jekyll new pippo

and the minima Jekyll theme.

Images

When editing post 2000-01-01-post-slug.md, create a folder images/2000/01/post-slug which contains all images relative to that post, then you can reference them with

![image decription](/images{{ page.id }}/image_name.jpg)

If you want the image to be responsive add the responsive CSS class

![image decription](http://image/url){:.responsive}

Link to post

Use the snippet [linked text]{% post_url yyyy-mm-dd-foo-bar %}, for example

See how to install [AWS Redshift compatible PostgreSQL client]{% post_url 2016-05-12-aws-redshift-compatible-psql %} article.

Libs

---
libs:
  twemoji: true
  katex: true
---

Post tags

Every tag can have a tag subfolder names as { tag | slugify }. To show it as a link in tag badges, edit _data/tagpage.yml; for example if there is only one post tagged with that keywork it does not make sense to list all of its related posts in a page. Furthermore, tag could by a typo or tag folder could not exist yet.

Components

HTML loadable components are defined in common/ folder and can be loaded using load-html, for example in any g14n.info HTML page you can load footer with the fillowing snippet.

<load-html src="//common/footer.html"></load-html>

Tricks

To escape Liquid tags, use {{ "{% this " }}%}. To escape {{ this }}, use {{ "{{ this " }}}}. Reference: How to escape liquid tags?.

Debug

It is highly recommended to install Jekyll to preview your site and avoid build errors before publishing it.

Install Jekyll

0. Install Ruby its dependencies (libxml2, patch) and Node as JavaScript runtime needed by execjs. With dotsoftware it is as simple as

.software_install Ruby
.software_install libxml2
.software_install patch
.software_install Node

1. Install bundler

gem install bundler

2. Install dependencies

bundle install

See as a reference:

• Using Jekyll with Pages
• Repository metadata on GitHub Pages
• GitHub Markup
• Jekyll Tips

Run Jekyll

Launch server running

npm start

Then you can connect to the site served locally on http://localhost:4000 or the admin panel on http://localhost:4000/admin

You can run it on a remote server, for example launching

npm start -- -H dev.g14n.info

Collections

Projects

Inspired by Tom Preston's article Readme driven development, documentation about my projects that does not use GitHub Pages is contained in their README.md file which is used to generate the project Homepage.

npm run readmes

Software

First of all, it is needed to create .gh-token file containing a GitHub token

All software I produce is on GitHub, metadata is downloaded via API with

npm run data:github:repos

and stored in _data/github/repos folder as .json files. Data is displayed in software page.

To keep software metadata and social badges updated, on a host that is always on, launch the worker

screen -S worker
npm run worker

then escape from screen session with CTRL-a d.

To add a new repo, foo for instance, just add an empty json file

touch _data/github/repos/foo.json

The name should not start with a dot, the only exception (by now :) is .software that is handled separately. The issue is that jekyll ignores dotfiles, so I need to name them dotsoftware. On the other side, having a repo named .software is a great advantage for its user experience: it makes sense.

npm scripts

GitHub badges

At first I started using shield.io, for example

https://img.shields.io/github/watchers/fibo/${reponame}.svg?style=social&label=Watch

but sometimes the badge goes unresponsive. Another solution is to use buttons from https://buttons.github.io but they cannot be embedded in a README.md on npm.

The final solution is to use static svg files generated by Jekyll.

For instance, repo foo has stars badge http://g14n.info/svg/github/stars/foo.svg which is generated by the following code

---
layout: null
---
{% assign repo = site.data.github.repos.foo %}
{% include github/stars.html %}

Licenses

I use the Artistic license for Perl projects, the MIT license otherwise.