minodi

my custom static site generator

Background

I recently started doing the fast.ai course and one of the research assignments was to start a blog and write about deep learning.

I’m not a fan of blog engines such as wordpress or ghost as I appreciate the simplicty of serving static sites using nginx. There is a lot of open source static site generators available. Hugo is a nice option, which is relatively minimal and easy to use. It does still have some “pain points” for me:

1. It does still have a lot of features that I do not need.
2. The theme creation/customization seems too complicated.

After looking at some other options I started to realize that these pain points seem quite niche to me and it’s probably unlikely for me to find something without them. So I started thinking about exactly what I wanted and it felt like something simple enough for me to put together in a relatively short amount of time.

Requirements

The basic use case is that I would like to write new posts in markdown format and have a command line script that converts them into html pages.

A list of the main requirements are:

1. Convert a folder of markdown files into html files.
2. Populate index page consisting of a blog listing section as well as other static content.
3. CSS styles for common markdown elements, including code syntax highlighting and formatted math notations.

Tools

• Pandoc -> To convert from markdown to html, Pandoc does an amazing job. I decided to use ./markdown/ folder for writing and ./posts/ as the output folder. To make the conversion, I use the following bash command:

  find ./markdown/ -iname "*.md" -type f -exec sh -c 'pandoc "${0}" --mathjax -o "./posts/$(basename ${0%.md}.html)"' {} \;

• GNU sed -> I have a few helper html files in the ./templates/ folder. These files contain placeholders for dynamic content such as a blog page, blog listing, or a page title. sed is used to swap out the placeholders, sed for macOS seems to have some limitations so GNU sed is used instead.

• highlight.js -> Syntax highlighting for code blocks.

• MathJax -> Displaying engine for rendering mathematics.

• Quick markdown example -> A sample markdown consisting of common markdown elements. This is used to build and test custom CSS styles.

• Solarized -> My favorite code syntax highlighting colors and used as a foundation to style the site.

Conventions

• Write in the ./markdown/ folder.
• Name the file YYYY-MM-DD.md.
• Start with a level 1 heading for every post. This becomes the title.

Usage

• ./build.sh -> To build the site, a few bash functions placed inside a file called ./build.sh, which builds the blog posts and compiles the site.

• ./deploy.sh -> To deploy the site, a one-liner script is placed in a file called ./deploy.sh, which uses rsync to copy the necessary files to a remote server. The script looks like:

  rsync -avz --exclude='.git/' --exclude='markdown/' --exclude="*.sh"  --exclude="\_*.html" ./ <username>@<host>:<remote-path>