I have been looking for a minimal way to generate my static website for quite a while. Many solutions out there simply feel to bloated for what I am trying to achieve, which is mainly:

• Write thoughts about interesting topics or my projects in a minimal environment (ideally something like vim or another simple editor)
• Use those thoughts as input and somehow convert them to a website
• Have a single style to decide what the entire page looks like
• Be able to use more complex features if I want to
• Have both input and output be small and local

I know that there are many great platforms out there, especially Bear blogs seem quite interesting to me but no platform so far felt as simple as I would like.

Let’s go over why my solution fulfills all my requirements (or view the finished project here)!

Simple editor experience

I believe when it comes to writing text in an editor, there is nothing simpler and more straightforward than a .txt file and whatever builtin Notepad-like editor your OS has, but this might be a little bit to minimal since it gives me no formatting options whatsoever. While generating a static site from pure txt input would also be a fun project, I felt for my blog I wanted to atleast be able to format code with syntax highlighting, include links and images, …

So here is the next best thing: Markdown!

I don’t think I have to explain markdown to anyone, but for those uninitiated: It’s basically like text files, but with a few formatting options, i.e. # for a heading, - for unordered list, [display text](link) for including links. If you want to find out more there is an open-source reference guide.

This would ensure the editing side is still extremely simple, learning the syntax takes about two minutes. Nice!

Converting thoughts to pages

But how do I take the thoughts I have written in my .md files and turn them into a webpage?

Well, websites are made up of HTML, so a converter that can generate .html file from .md files would be nice. Luckily, I have already installed a behemoth of text conversion on my system: Pandoc.

By typing

pandoc [INPUT_FILE].md -o [OUTPUT_FILE].html

pandoc takes care of all the hard work and almost instantly we have converted our thoughts in markdown to valid HTML.

One style, many pages

Pandoc has surprised me by supporting templates. This solves our style problem without even having to think about it to much. We can simply create a template.html file that hold some placeholder values which pandoc will replace by their actual content:

<h1>$title$</h1>

would turn into

<h1>Smallest static site generator (sssg.sh)</h1>

for this post. Similarly, there is the $body$ placeholder that will contain the rest of the markdown document body.

If we now define our CSS in a <style> tag at the beginning of template.html, we can use one style for all the markdown files we have - assuming we generate all of them into that template.

Now here comes the fun part, we can create a shell script to automate this process for us. It will look through all subdirectories, find each file with a .md extension and pass it to pandoc:

for i in $(find . -name "*.md");
do
    pandoc "${i}" -p "${i%.md}.html" --template=template.html
done

Adding complexity

I did not want to have only text written by me on my page. I wanted friends and family to be able to comment and sign my textbook. This means, I needed to have some interactivity.

Now the comment system itself was something I had to implement inside the backend. It’s basically just a database that anyone (please don’t doxx me) can post into. But my goal for the site was to make it easy to implement these features into my blog posts and reference more complex functionality inside of my markdown files ideally.

Luckily, pandoc comes to the rescue again! I learned that, if you just straight up include HTML elements in your notes they will cleverly be ignored by pandoc and thus remain functional in the final document.

That means that this markdown down below is valid syntax:

**Guestbook**

[Sign](guestbook.php)

<?php include "res/src/guestbook.php"; ?>

The guestbook.php script gets all comments from the DB and displays them.

I’m lazy.

Having to setup something locally so I could make PHP requests to my DB was way to cumbersome for me. I just wanted to have a quick and dirty way to preview my pages in HTML and later, when I was sure they could be uploaded, they needed to be converted to PHP.

So what I did was add an argument to the build script I had previously created to select whether I wanted to create .php or .html files:

output_format="php"

if [ "$#" -eq 1 ]; then
    if [ "$1" == "html" ]; then
        output_format="html"
        echo "Building as .html"
    elif [ "$1" == "php" ]; then
        output_format="php"
        echo "Building as .php"
    else
        echo "Invalid argument. Usage: $0 [html|php]"
        exit
    fi
else
    echo "No argument provided. Usage: $0 [html|php]"
    exit
fi

And since PHP files are just renamed HTML files I could simply swap out the extension later:

if [ "$output_format" == "php" ]; then
    mv "../out/${filename_without_ext}.html" "../out/${filename_without_ext}.php"
fi

Great, so now I can select whether I want to preview the files locally (bash build.sh html) or upload them to the server (bash build.sh php).

Small and local

Aaand.. that’s basically it!

Last on the list was to have both input and output files local and small, and since I only have a shell script in my directory that converts markdown to HTML files, I think there is not that much overhead left to remove.

The final setup

If you are curious to see the entire build script check out its repository! This blog is also generated using the script (of course). Please feel free to let me know what you think about it, any improvement ideas are welcome!

Comments

Leave a comment

https://ad301.org/ [Blog - Smallest static site generator (sssg.sh)] [+]

0,0-1

All