Static site generator

This static site generator is designed to render markdown with LaTex to static HTML pages with as little fuzz as possible. I used it to make rubenvannieuwpoort.nl. It is explicitly designed to fit my needs, so it will not have support for many features.

Note that the generator is very simple. In particular, it has no concept of a theme. If you want to adapt the look, you should directly modify the HTML and CSS (or the scripts that generate them).

It utilizes node.js, markdown-it, and KaTeX through the markdown-it-katex plugin, and a shell script to build the site.

Folder structure:

index_files: the files that are needed by index.html.
posts: the folder that contains the posts in a markdown format.
- post_list: contains a description of the posts you want on your site. This way, you can have unfinished posts in your 'posts' folder; they are only added to your generated site once you add some metadata to posts/post_list.
post_files: files that are copied to the posts folder on your site. This folder might contain common CSS, javascript and whatnot.
scripts
- format_blogpost.js: a javascript script that parses a markdown post file and generates a static html page from it.
- format_index: a bash script that takes post_list files as input and generates the main page, which is a simple overview of the posts
site (only exists after building): folder that holds your static site when it is generated
build: the build script you have to execute to generate your site in the site folder

This static site generator is meant to suit my needs. It is almost certainly not suitable for your needs out-of-the-box. The idea is that it is relatively lightweight and easy to adapt to your needs. It does not work with plugins or themes. It is able to render math in LaTeX, when it is delimited with dollar signs (for inline math) or double dollar signs (for math in 'display mode'). It outputs pure HTML and CSS and doesn't output any javascript.

Example

Make sure you have node and npm installed, then run:

git clone https://github.com/rubenvannieuwpoort/static-site-generator --recursive
cd static-site-generator
npm install
./build

Now, a site directory should have been created, which contains the generated site.

If you want to build the site in a way that you can open it locally with the links still working, use ./build dev instead of ./build. This makes sure the links in the index include the .html suffix so that they link to local files.

Configuration

This generator will create a site with just two types of pages. An index page, which contains a list of links to blog entries. This page is generated by the format-index script. The posts are contained in the posts folder. They should be in markdown format. Some metadata of the blog posts is specified in posts/post_list. This file contains three tab-separated columns:

The post title
The filename of the markdown file (assumed to be in the posts folder), without the "md" extension.
A description of the blog post.

This data is read by the build script and by scripts/generate-index.

Description of the build process

The build script contains the build process. In words, it does the following:

1. For each line in posts/post_list:
    run scripts/format-blogpost <TITLE>, save the output to site/posts/<FILENAME>.html
2. Copy all files from post_files/ to site/posts, and all folders from posts/ to site/posts
3. Run scripts/format-index and save the output to site/index.html

The files in index_files and post_files will get copied to the file containing the index and blog posts, respectively. This makes it possible to link to these files in the HTML files using relative paths.

The posts should be in markdown format in the 'posts' folder, and use the .md extension. To generate the site, simply run build. A folder 'site' will be generated, which contains your site. You don't need to run a server to look at the files, so you can just doubleclick index.html to see the result. To remove the generated site, run build clean.