Contents

Static site generators

Pros and Cons of static site site generators (SSGs).

Prologue

I’ve always wanted to have a tech blog that is

  • looking nice πŸ₯°
  • fast and responsive
  • having full-text search
  • tracking the progress I made
  • browser through keywords for my articles
  • displaying math and chemical expressions

Hugo

Hugo is the world’s fastest framework for building websites, written in Go.

Pros πŸ‘

  • Single dependency with one hugo excutable only.
  • Extremely fast. It builds a large website within 5 seconds.
  • Able to customize / override default settings without messing up the theme files.1

Cons πŸ‘Ž

  • A limited number of extensions.
  • GoLang knowledge is required if you want to make templates.

Themes

Hexo

Pros πŸ‘

  • A huge set of plugins thanks to the npm ecosystem.
  • Plentiful Chinese resources.
  • Relatively fast. It builds a large website under 1 minute.

Cons πŸ‘Ž

  • Hundreds of npm dependencies. If you are familiar with npm packages it might not be a problem.
  • For LaTeX math typesetting, you need to change the renderer to either the pandoc one, which requires the pandoc binary or the markdown-it one, in which chemical typesetting (mhchem) does not work well.
  • More complicated to override the templates in the theme.
  • Less intuitive asset management.

Themes

Docsify

Docsify renders Markdown files to HTML on-the-fly.

Pros πŸ‘

  • Minimal dependency: just one index.html with JS/CSS and you’re good to go.
  • Fast. It skips the building step and renders Markdown file on-the-fly.
  • Handy extensions on awesome docsify.

Cons πŸ‘Ž

  • No support for tags and categories.
  • KaTeX extension does not support mhchem.

Others

  • Jekyll, the default GitHub pages SSG written in Ruby. Generating a large site is slower compared to either Hugo or Hexo, taking several minutes.
  • Nikola, a SSG written in Python with first-class support of Markdown (*.md), reStructuredText (*.rst) and Jupyter Notebook (*.ipynb) files.
  • JupyterBook, powered by the Sphinx python documentation generator, builds beautiful, publication-quality books and documents from Markdown (*.md), reStructuredText (*.rst) and Jupyter Notebook (*.ipynb) files.
  • Gatsby.js is a blazing fast React-based open-source framework for creating websites and apps. Some Javascript Node.js knowledge is required to build a site.

Conclusion

Right now I use Hugo with codeIT theme in my blog (see the footer), but keep some templates in case I need to make the switch.


  1. In Hugo, you are able to override default layouts and settings by placing counterpart file(s) in your site folder. Hugo will look at your custom setting first without messing with the theme folder, which is much more friendly for Git submodules and theme updates. ↩︎