Date: Thu Nov 8 23:48:54 EST 2018

Website frameworks

Are an interesting beast. The purpose is not always immediately obvious. They provide scaffolding to ease something. What that is can vary wildly depending on the framework in question.

Let’s take a few examples:

They all have rather different goals and do things in vastly different ways.

The all however have one thing in common, they do way more than is necessary just to display some text onto a page for you to read.

There are many other brilliant authors who’ve dissected the problem that the software industry has, many of which can be found on harmful.cat-v.org as well from others such as Bryan Lunduke and many, many more as to which I’m unable to recall at the time of writing.

One quick way of summarizing the problem with software is something along the lines of:

Unlike other engineering disciplines the process of engineering a piece of software is not to simplify, reduce complexity, identify the possible ways it can fail, reduce memory usage and other resource consumption, continuing the optimization until it’s no longer possible.

No instead the process of software engineering has become a game of how many fucking abstractions can you use to make your life a living hell just so impress your boss with the complexity and resource requirements of your piece of shit application.

Why this madness not only exists, but is commonplace in the industry I will visit another time as it’s outside the scope of this entry.


A simple solution to the madness of complex websites and frameworks

An “un-framework” perhaps one might call it. Write markdown, concatenate a couple of files and put it on your web server.

How? We’re going to use a simple program written in C called sundown and a couple of shell scripts. You can substitute sundown for any other markdown rendering program you’d like by editing the shell script.

First things first, go grab a copy of sundown from github and build it with make sundown

Place the binary in your $PATH with install -m 555 sundown /usr/local/bin/sundown or similar.

A quick test to see if it is working:

$ echo "# H1 test" | sundown

should return:

<h1>H1 test</h1>

Now it’s time for the big scary “framework”:

$ git clone https://git.riedstra.us/mitch/unframework.git

Once you’ve cd’d to the directory in question you can then render the sample site:

$ bin/render ../site

Doing so will take every .page file under the unframework directory, including subdirectories as well as any related files ending in .head or .tail that will be prepended or appended to the .page respectively and render an HTML file.

There are a couple of minimal includes including a common head file in inc/head.html which can be used to specify static assets.

Static assets are not handled by the framework, but you can easily copy them over to your site directory with something along the lines of:

cp -R static ../site/

Included in the framework is a small css file that will make your website look a little bit better.

That’s about it. For those reading who don’t want to go through digging through the repository the source code for the entire framework is below:

bin/render

#!/bin/sh
set -e
RENDER="bin/render_single"

dest="$1"; shift

if [ -z "$dest" ] ; then
	echo "Please supply a destination directory"
	exit 1;
fi


if ! [ -d "$dest" ] ; then
	mkdir -p "$dest"
fi

pages="$(find . -type f -iname '*.page')"

for page in $pages ; do
	page="$(echo "$page" | sed 's@\.[^./]*$@@')"
	page_dirname="$(echo "$page" | sed 's@/[^/]*$@@')"

	if ! [ -d "${dest}/${page_dirname}" ] ; then
		mkdir -p "${dest}/${page_dirname}"
	fi
	$RENDER "${page}" > "${dest}/${page}.html"
done

bin/render_single

#!/bin/sh
set -e

page="$1" ; shift

if [ -z "$page" ] ; then
	echo "Please supply a page to render"
fi

page="$(echo "$page" | sed 's@\.[^./]*$@@')"

page_heading="${page}.head"
if ! [ -e "$page_heading" ] ; then
	page_heading="inc/head_close.html"
fi

page_tail="${page}.tail"
if ! [ -e "$page_tail" ] ; then
	page_tail="inc/body_close.html"
fi

cat inc/head.html "$page_heading"
sundown < "${page}.page"
cat "$page_tail"

FAQ

Doesn’t markdown add an unnecessary layer of complexity of building a simple website?

Yes and no. Depending on how you view it. Yes if HTML were a sane standard that might be the case. When HTML is a bastardization of SGML that’s both hard to write and read the only unnecessary complexity is converting from a sane format such as markdown to the insane format of html viewed by your web browser.

What about sitemaps?

They’re not really that useful unless you have dynamic content that you want indexed.

What about a RSS or Atom feed?

Outside the scope of this “framework”

What about templating?

If you really hate simplicity there’s Mustache, and a C version.

Can I dynamically render the website when a file is changed?

Sure, it shouldn’t be hard to write a program in C to use inotify(7) or kqueue(2) to call bin/render but again. It’s outside the scope of this “framework”

Or better yet, just configure your editor to do it on save and save yourself the time.

Can you help me configure my web server for this?

No.

What are you, some sort of un-hipster that hates cool new things?

Whatever makes you sleep at night.