articles

+

makefile

+

template

=

blog

sblg is a utility for creating static blogs. It knits together articles with templates to generate static HTML files, Atom feeds, and JSON files. It's built for use with make(1). No markdown (unless…), no CMS, no CGI, no PHP. Just a simple UNIX tool for pulling data from articles and populating templates. sblg is an open source ISO C utility that depends only on libexpat.

how it works

You write your HTML articles and templates. sblg(1) pulls data from the articles and merges it into the templates. (This is all usually orchestrated with a Makefile.) That's it.

There are two basic ways of populating templates: a standalone mode, which pastes a single article into a template; and an amalgation mode, which posts multiple articles—like a blog front page. Amalgamation mode can merge entire articles as well as just article snippets and metadata for navigation and summary purposes. That's what this page does. You can also do specialty modes of Atom and JSON feeds—also part of this page.

To get started, download sblg.tar.gz (SHA512), decompress, run ./configure then make install. The current version is 0.4.17, released on . The repository is mirrored on GitHub, if that's easier for you. There's also a Homebrew formula in BSD.lv's tap. The last few versions featured the following (this was created by showing only select bits of newest three version articles):

latest versions

(See all versions.)

standalone mode

standalone mode graph

Articles are just content within the <article data-sblg-article="1"> tag of an HTML (or really XML) document. sblg(1) pulls articles and article metadata for populating navigation elements and article elements in the templates. Some of the bits extracted are noted within the example. You can also set variables, such as foo in the following, that can be used in the template. The following is an example article:

<?xml version="1.0" encoding="utf-8"?>
<article data-sblg-article="1">
  <header data-sblg-set-foo="bar">
    <h1>first hN sets document title</h1>
    <address>sets author name</address>
    <-- the datetime being the article's date… /-->
    <time datetime="2014-04-12">2014-04-12</time>
  </header>
  <aside>
    This is pulled out for the page synopsis.
  </aside>
  <p>
    And here we have some <q>content</q>.
  </p>
</article>

You'll also need a template. For standalone mode, this is just a regular HTML file where the <article data-sblg-article="1"> tag is replaced by the page contents.

<!DOCTYPE html>
<html lang="en">
  <head><title>${sblg-titletext}</title></head>
  <body class="${sblg-get|foo}">
    <article data-sblg-article="1"></article>
  </body>
</html>

There are all sorts of things documented in sblg(1) that templates can fill in as extracted from article text. These are typically used in HTML <meta> elements and so on.

This works well for putting simple documents into a template. But what if we want to have these documents relate to each other, or have a single document relate to multiple articles? That's where amalgamation mode comes into play.

amalgamation mode

amalgamation mode graph

For amalgamation (blog) mode it's the same; however, you can also specify <nav data-sblg-nav="1"> to fill in meta-data from all articles passed into the command. The <article> elements will be filled in with articles.

<!DOCTYPE html>
<html lang="en">
  <head><title>My Blarg</title></head>
  <body>
    <nav data-sblg-nav="1"></nav>
    <article data-sblg-article="1"></article>
    <article data-sblg-article="1"></article>
    <article data-sblg-article="1"></article>
    <article data-sblg-article="1"></article>
  </body>
</html>

A Makefile makes this easy. Pretend that your articles (article1.xml, article2.xml) are source code. Then object files (article1.html, article2.html) are compiled from single articles and a template, article.xml. Binaries (index.html are compiled from object files (or directly from sources) and a template, index.xml.

.SUFFIXES: .xml .html
XMLS = article1.xml article2.xml
ARTICLES = article1.html article2.html
all: index.html $(ARTICLES)
index.html: index.xml $(ARTICLES)
	sblg -o $@ -t index.xml $(ARTICLES)
.xml.html:
	sblg -o $@ -t article.xml $<

To read about the system, read the sblg(1) manual. I take great care in making sure that the manpage is up to date; less so the non-canonical howto and FAQ documents. That said, this is about blogs, so you might as well have some bloggy stuff. This index is also created dynamically from all howto articles. Unlike the version index above, each links to the full articles, all of which were created with sblg(1)'s standalone mode.

standalone amalgation mode

standalone amalgamation mode graph

A common usage is to mix up standalone and amalgation mode, where each article has its own page, and each page refers to all other pages. This can be effected using standalone amalgation mode (-C), which specifies a single article for display (like with standalone mode) but may reference multiple other articles in navigation.

<!DOCTYPE html>
<html lang="en">
  <head><title>Blarg page: ${sblg-titletext}</title></head>
  <body>
    <nav data-sblg-nav="1"></nav>
    <article data-sblg-article="1"></article>
  </body>
</html>

For larger numbers of pages in standalone amalgamation mode, the cost of recompiling for each output can be quite high. So there's also a mode (-L) for producing one output for each input, given all inputs.

some random articles