💾 Archived View for gmi.karl.berlin › blog.html captured on 2021-12-04 at 18:04:22.
⬅️ Previous capture (2021-12-03)
-=-=-=-=-=-=-
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>My Simple Custom Blog Software</title>
<link href="http://www.karl.berlin/atom.xml" type="application/atom+xml" rel="alternate" title="Atom feed for blog posts" />
<style>
body {
font-family: sans-serif;
margin: 0 auto;
max-width: 48rem;
line-height: 1.45;
padding: 0.5rem 0 1.6rem;
box-shadow: 0 0 2rem 0 #bbb;
border-radius: 0 0 0.6rem 0.6rem;
}
main {
padding: 0 1.4rem;
hyphens: auto;
}
code {
background: #eee;
padding: 0.3rem;
}
pre code {
display: block;
overflow-x: auto;
padding: 0.3rem 0.6rem;
}
nav ul {
margin: 0;
padding: 0;
display: flex;
background: #17a;
}
nav li {
list-style: none;
}
nav li * {
display: block;
padding: 0.4rem 0.4rem;
color: white;
}
nav li strong {
padding-left: 1.5rem;
padding-right: 1rem;
}
nav a {
text-decoration: none;
}
nav a:hover {
background: #069;
}
</style>
</head>
<nav>
<ul>
<li><strong>Karl Bartel</strong></li>
<li><a href="index.html">Home</a></li>
<li><a href="projects.html">Projects</a></li>
</ul>
</nav>
<main>
<h1>My Simple Custom Blog Software</h1>
<p>The pages on this site are generated by my own primitive blog engine. This post summarizes why I wrote my own, what my priorities for it were and how I went about achieving them.</p>
<h2>Why Something Custom?</h2>
<p>Originally I wanted to use <a href="https://gohugo.io/">Hugo</a> for this blog. I started to look for a simple theme that did not involve many dependencies and provided clean output. This quickly frustrated me because the themes were either not minimal at all or I could not get them to work with my version of Hugo. This made me take a step back and think about what I actually want as blog output. I wrote a tiny HTML header, a small test blog article in markdown and did
<code>cat header.html > post.html && smu post.md >> post.html</code>. The result looked good and that convinced me that writing a small blog creation script was more rewarding and maybe even faster than configuring something existing the way I like it.</p>
<h2>Requirements</h2>
<p>Before jumping deeper into it, I made a list of my basic requirements:</p>
<ul>
<li>Low maintenance</li>
<li>Low barrier to create content (markdown)</li>
<li>Low requirements on the client (web browser, internet connection, RAM, CPU)</li>
<li>Shows creation and update timestamps of posts</li>
<li>RSS feed</li>
</ul>
<h2>How I Achieved These Constraints</h2>
<h3>Low Maintenance</h3>
<ul>
<li>Avoid dependencies: only a POSIX shell and a markdown converter are required. Dependencies always increase the maintenance burden.</li>
<li>Static files: hosting static files is much easier to do reliably than hosting dynamic content</li>
</ul>
<h3>Low Barrier to Create Content</h3>
<ul>
<li>Use markdown: when writing markdown I can mostly avoid thinking about the syntax and focus on the content</li>
<li>Automatically generate timestamps: generating the timestamps from the git history allows me to just create posts without needing any templates or front matter to provide this data. I also can't forget to update these timestamps.</li>
</ul>
<h3>Low Requirements on the Client</h3>
<p>This is mostly solved by not doing anything complicated. Not adding any JS and CSS frameworks keeps the size small. Not setting a font size and not disallowing zooming makes the text readable on a wide variety of devices and by people of bad eye sight. Just using basic HTML and a few lines of CSS allows old or limited browsers and slow computers to display the page easily. I could go on for a long time here, but I'm sure you get the concept.</p>
<h3>RSS Feed</h3>
<p>Adding an RSS feed (an <a href="https://en.wikipedia.org/wiki/Atom_(Web_standard)">Atom</a> feed to be precise) was the most complicated part of the script. But I really love RSS and in my opinion RSS support is an essential part of a blog. I was shocked to learn that nowadays some blog engines need plugins to get RSS support!
Writing something that is nearly a valid Atom feed is pretty easy. Just take the <a href="https://validator.w3.org/feed/docs/atom.html#sampleFeed">example Atom feed</a> and fill in your own values. But to make it standard compliant and work well with different clients, I also needed to</p>
<ul>
<li>Use an absolute feed URL. I usually avoid absolute URLs, as that makes local testing easier.</li>
<li>Generate good IDs for the posts. This was the hardest part, see <a href="http://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id">Mark Pilgram's recommendations</a> to see the challenges in detail.</li>
<li>Include the post content while escaping the HTML tags</li>
</ul>
<h2>Results</h2>
<h3>The HTML Output</h3>
<ul>
<li>No JS, no tracking, no custom fonts</li>
<li>No external CSS</li>
<li>Minimal styling</li>
<li>This page weighs just 7K, most of it the text you are reading right</li>
</ul>
<p>The largest part of the CSS is the styling of the navigation bar. I could have went with a line of text links separated by spaces, but I wanted to have a clearly visible navigation at the top.
Using such a small amount of CSS also removed the need for any CSS preprocessors like <a href="https://sass-lang.com/">Sass</a>. </p>
<h3>The Blog Script</h3>
<p>You can find the <a href="https://github.com/karlb/karl.berlin/blob/master/blog.sh">code of the resulting script</a> on github. The blog you are currently viewing is part of the same repository and serves as example content.</p>
<p>To make the script work as intended, you should adhere to the following rules:
<ul>
<li>Use git and don't edit history after publishing. This is required for the automatic timestamp generation.</li>
<li>All posts and the <code>index.md</code> have a title using the <code># </code> syntax. This title is used for the HTMl title tag and for the post titles in the article listing and RSS feed.</li>
<li><code>header.html</code> contains an absolute link to your <code>atom.xml</code>, including a hostname you control. This is necessary to build a correct atom feed.</li>
<li>Uncommitted files are drafts and won't show up in the normal article list, but are shown in <code>index-with-drafts.html</code>.</li>
</ul>
</p>
<p>Feel free to contact me if you have any questions. If you want to use it for your own site, I can give some guidance. Since I don't expect many users, this is less effort than writing and maintaining good documentation.</p>
<small>Written on 2020-08-30.</small>