💾 Archived View for gerikson.com › gemlog › srs-bzns › Gemlog-with-Blosxom.gmi captured on 2021-12-03 at 14:04:38. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

The occasional geminer - an artisanal, handcrafted gemlog

↑ latest entries

Setting up a gemlog with Blosxom

I've used [Bloxsom] for ages for my blog. It's a nice simple system with a lot of plugins for more powerful functionality.

Blosxom

Prerequisites

You need your own Unix host connected to the internet.

You need to have a gemini server installed and working.

You need Perl installed.

Setup

Download the `blosxom.cgi` file from the site. Plunk it in a logical place. You can set it to be executable, or just call `perl ./blosxom.cgi` directly.

Open it in your favorite editor.

The configuration steps are detailed here:

http://blosxom.sourceforge.net/documentation/users/configure/

Here are the relevant parts from my personal setup. Comments with [brackets] are my clarifications.

# What's this blog's title?
$blog_title = "gerikson.com gemlog";
# What's this blog's description (for outgoing RSS feed)?
$blog_description = "gemlog via Blosxom";
# Where are this blog's entries kept?
$datadir = "/home/gustaf/gemsite/gemlog-data";
# What's my preferred base URL for this blog (leave blank for automatic)?
$url = "gemini://gerikson.com/gemlog";
# What file extension signifies a blosxom entry?
# [change this to whatever you want if you prefer Markdown, for example]
$file_extension = "txt";
# What is the default flavour?
# [Specific for gemini, default is 'html']
$default_flavour = "gmi";
# --- Plugins (Optional) -----
# Where are my plugins kept?
$plugin_dir = "/home/gustaf/gemsite/gemlog-plugins";
# Where should my plugins keep their state information?
$plugin_state_dir = "$plugin_dir/state";
# --- Static Rendering -----
# Where are this blog's static files to be created?
# [This is where your Gemini serve gets its content!]
$static_dir = "/home/gemini/gemini/gemlog";
# What's my administrative password (you must set this for static rendering)?
$static_password = "SuperSecret";
# What flavours should I generate statically?
@static_flavours = qw/gmi atom/;
# Should I statically generate individual entries?
# 0 = no, 1 = yes
$static_entries = 1;

The stuff that's different from a normal HTML blog is the flavour(s):

gmi - gemtext
atom - Atom feed, handled by a plugin

Static rendering

By default, Blosxom is a CGI application that reads from the filesystem directly. This is fine in its way but for gemini we want to keep it simple and static.

Plugins

Plugins help extend Blosxom. The canonical list is here:

http://blosxom.sourceforge.net/plugins/

But not all plugin links are live! You might have to google them, or grab them from my repository:

https://github.com/gustafe/gemsite/tree/main/gemlog-plugins

Here are the ones I use:

prefs - enables preferences
meta - enables metadata in posts
atomfeed - enables an Atom feed
date_fullname - Monday instead of Mon, etc
entries_template - configures how entries are presented
entriescache - keeps posting dates intact
flavourdir - enables you to keep flavour files in your data directory, instead of in the plugin directory
pagetype - enables conditions based on pagetype
fmtcat - presents a nicely formatted string of the current category path
interpolate_fancy - better interpolation support

Setting up for gemtext

By default, Blosxom will generate (non-semantic) HTML4. You are expected to write your posts in straight HTML. We will leverage that to serve straight gemtext.

First, we need to customize each page for the `gmi` flavour. This will override the default HTML flavour.

Create a directory `flavours` in your data dir. Create and edit the following files:

head.gmi
date.gmi
story.gmi
foot.gmi

My current settings are visible here:

https://github.com/gustafe/gemsite/tree/main/gemlog-data/flavours

I use `head.gmi` for stuff like the name of the blog, links to the main page, etc. `foot.gmi` contains copyright/licensing. I leave `date.gmi` empty.

`story.gmi` looks like this

# $title

$body

––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
=> $url$path/$fn.gmi ¶ $date_fullname::dw, $yr-$mo_num-$da
=> $url$path/ » more posts in the ‹$fmtcat::fmtcat› category
$meta::updated
About this category: “$category_desc::description”

Each story will have a 2nd level title (grabbed from the source file), the body, and then a permalink. Note that this is straight gemtext.

gemlog style main page

By default, Blosxom will present a page like this

HEAD
  DATE
    STORY
    STORY
  DATE
    STORY
  [...]
FOOT

But gemlogs want to look like this

HEAD
=> link to DATE - TITLE
=> link to DATE - TITLE
[...]
FOOT

To enable this, we'll use the `entries_template` plugin. Its config file lives in the `flavours` subdir too. Mine looks likes this:

=> $url$path/$fn.gmi $yr-$mo_num-$da - $title

Note the permalink construction is the same as in the story template.

First post!

We're ready to start gemlogging!

Fire up an editor and write a piece of gemtext in a file ending with `.txt` in your `$datadir`. You can use subdirectories if you want, these will essentially be categories.

Then run the following command:

$ perl ./blosxom.cgi -password='SuperSecret'

This should generate a bunch of files in the location denoted by `$static_dir`. Point your gemini browser and you should see a front page with your first post as an entry.

If you open the post again, the `entriescache` plugin should have added a `meta-created-date` line just under the first line.

By default you can get to the post via the following links:

gemini://mysite/mypost.gmi
gemini://mysite/2021/10/06/mypost.gmi

The following URLs will show pages with links:

gemini://mysite/directory (if you have your posts in a directory)
gemini://mysite/2021 - all this year, add /$month and /$month/$day to get month and daily views, respectively.

For example:

gemini://gerikson.com/gemlog/misc/

gemini://gerikson.com/gemlog/2021/10

gemini://gerikson.com/gemlog/2021/

Each subdirectory/date will have its own Atom feed, too.

This setup gives you flexibility in how to present your content, construct permalinks, etc.

Re-rendering your gemlog

Add the configuration `-all=1` to force a re-read of all files, not just new and edited ones. Use the `-quiet=1` option to suppress output.

Getting fancy

This is a setting carried over from my blog. I only want a dozen or so posts on my front page, while if I navigate to a category or a year, I want to see all of the posts.

By default, Blosxom will show the number of posts defined in the `$num_entries` variable in the config, irrespective of the view chosen.

The plugins `prefs` and `pagetype` help with this. `pagetype` identifies the type of page ('chrono', 'category', or 'story'), while `prefs` allows you to dynamically change the `$blosxom::` variables.

In the top-level of my `$data_dir` I have the file `pageprefs`:

if (($pagetype::pagetype eq 'chrono') or
    ($pagetype::pagetype eq 'category')) {
      $blosxom::num_entries = 999 }
else {
     $blosxom::num_entries = 15 };

This will show 15 entries on the front page, but 999 on date or category pages.

────────────────────────────────────────────

Updated on Sunday, 2021-10-10

✽ Wednesday, 2021-10-06

→ more posts in the ‹srs-bzns› category

About this category: “serious business - everything here is worth your time”

Main page for this gemsite