A new beginning

Introduction

A static site generator is basically a computer program that usually runs on your personal computer which mission is to transform a list of plain text files (usually written with a lightweight markup language) into a well organized folder structure with html files. It main benefit is to avoid the hassle of writing directly the HTML files and keep in order the folder structure so the web page is easy to navigate.

Nowadays, there are several lists of static site generators. The decision of choosing one instead of other will depend on several factors, the main one, in my opinion, the disposability of a good theme that cover yours needs. My personal decision was to choose Hugo because it is fast, easy to use and has a comprehensive list of themes. In fact, the Academic theme by George Cushen (in which the design of my front page is heavily inspired) pushes me to make the decision.

But, what is a static site and why use a static site generator?

Eduardo Bouças has a fantastic and detailed introduction to this topic that covers everything you need to know in order to take a decision of moving your site to a static generator. In the following I will present a brief discussion about what a static site generator is and my own motivations to use it.

According to wikipedia:

A static web page is a web page that is delivered to the user exactly as stored, in contrast to dynamic web pages which are generated by a web application.

Roughly speaking, a dynamically generated web page is created (almost) every time a user wants to access it (i.e. every time the user writes the url in a web browser and hits enter). This is quite convenient for a news site where the content is constantly changing but requires a good server infrastructure, maintenance (usually upgrade the program that takes care of generating the content) and, most of the time, some programming knowledge and server configuration.

On the contrary, a static site is just a bunch of html pages stored in the web server so no special infrastructure nor maintenance is required. The big disadvantages are:

• no real-time content is possible in this way (unless we are constantly connected to the server changing the files),
• no user feedback (comment system for instance are not possible, although there are some workarounds), and
• no admin section to change the content directly from a browser (think how easily is to publish and change a blog post in Wordpress or Medium).

Why use a static approach then? Because it is fast, secure, does not need any special infrastructure nor server configuration and, thanks to a static site generator, it is easy to maintain. The key point is the last one: the advent of static site generators has made this option not only viable but also rather convenient for certain purposes. Actually, a personal web page or a portfolio are good examples where static site suits the best. As Eduardo Bouças says “static sites are for everyone but not for everything”.

In my personal case, this web page is hosted in my institution server, which is a very basic one. This constrains the possibilities for a dynamically generated site (although they provide with a dynamic server basic enough for some purposes it only allows to install some content management system and require workarounds to work properly). In my own experience, it is difficult to configure satisfactorily a Drupal or Wordpress site.

Hugo: the world’s fastest framework for building websites

Hugo is one of the hundreds static web generators out there. As I pointed out in the previous section, it is my personal and opinionated choice for managing this website.

This does not pretend to be an introduction to Hugo so just take a look to the official web page and the quick start guide to figure out by yourself it it suits your needs. Do not forget to visit its theme showcase!

However, I will present some Hugo features that help me to design this site:

All in a binary file: the hole program is contained in a single binary file so we can save both the site (all the css styles, img and content) together with the Hugo executable. Hence, as long as the executable works we will be able to reproduce the hole site from the content files.

Markdown support out of the box. I have recently discovered that markdown format is a really convenient way of writing documents. It is a future-proof format since it is just a plain text files and the markup is so simple that does not disturb reading it. Moreover, the pandoc command line utility allows to transform any markdown file in different formats including HTML, LaTeX, pdf or epub (for ebooks).

Data templates: Hugo supports loading structure data from a file (in the YAML, JSON or TOML format). This is rather handy for keeping organized my publication list. Think about a data file as a small database that Hugo knows how to process and show in the templates. The following is a small extract of my publications.toml data file (in TOML format):

[[paper]]
  preprint = false
  title = "Parallel mean curvature surfaces in ..."
  abstract = "We survey different classification ..."

  DOI = "10.24064/iwts2016.2017.8"
  mrcode = ""
  zbl = ""

[[paper.author]]
  name = "José M. Manzano"
  mathscinet = "944440"
  url = "http://www.ugr.es/~jmmanzano/"
[[paper.author]]
  name = "Francisco Torralbo"
  mathscinet = "874912"
  url = "http://www.ugr.es/~ftorralbo/"
[[paper.author]]
  name = "Joeri Van der Veken"
  mathscinet = "800860"
  url = "https://perswww.kuleuven.be/~u0043959/" 

[paper.journal]
  name = "Proceedings Book of International ..."
  abbr = "Proc. International Workshop on ..."
  volume = "1"
  year = "2016"
  pageStart = "57"
  pageEnd = "78"

[paper.arxiv]
  id = "1701.03740"
  cathegory = "math.DG"

Every publication is store in this way one after the other in the same file. This has two different advantages:

• The flexibility of the TOML format allows to add new fields to the file structure in the future and handle the new data in Hugo templates. For instance, I can add the number of cites of each paper including the line cites = "17" and then change the template to show this data. Moreover, I will be able to collect all the cites and automatically compute the total number of them.
• If I decide to redesign the way the publication list is shown, I only have to change the template responsible of loading the data file and Hugo will render the complete list of publications using the new style.

The design

When I first started using Hugo I installed the marvelous Academic theme by George Cushen. The design of the main page of the site is fantastic. But after trying to tweak some of the elements of the page as well as to organize my content in a different way I realized it will be easy to write down my own design from the ground up. I indebted to the author a lot since studying how the theme was designed I learnt a lot about how Hugo template system actually works. I have to admit that some parts of the Hugo template system are still a mystery for me and some of the features I included in the design were difficult to achieve.

On the one hand, the front page is a copy of his but using different CSS technologies (the new grid system as well as flexbox). On the other hand the blog section is completely new. The layout is loosely inspired in some newspaper sites like The New Yorker, Quanta magazine and the content follows the Edward Tufte CSS style. I am planning to convert my design in a Hugo theme in the (not near) future.

What next?

There still a lot of imperfections in the design as well as some features that I would have liked to include before releasing the new site. With no particular order:

• Add a comment system, probably using an existing social network (like twitter) to manage them.
• Create a pandoc-LaTeX template to convert the markdown content files to pdf. In the meanwhile, the print button just open the print dialog of the browser.
• Include a version log for any entry so track changes will be easy
• Configure a version control system (git) for the content and the theme.