blog

Blog is a tool to create a semi-ephemeral™ blog with a "permanent" archive on gemini.

The Ephemeral Blog.

Whenever you generate your blog, it will keep only the first 3 files and render an html page, an rss feed and a plaintext file.

Posts will disappear as you add new ones.

The archive

Not everything is ephemeral, as we also generate an archive of the whole blog in gemini format.

Installation

At the moment only installation from source is available. Clone this repository and run pnpm install -g .. This will add the blog command to your shell.

Usage

How to add a new entry

Create a .gmi gemini file.

You can add this to the blog using the following command, it will shift all entries and remove the oldest one if limit of posts is reached (defualts to 3):

blog --add path/to/blog_post.gmi

These commands will regenerate the static files. At that point you can preview your blog by serving the files on the static directory.

How to update the latest entry

If you need to make corrections to the latest entry, use:

blog --update path/to/blog_post.gmi

This will replace the latest with the contents of the path without shifting the existing entries.

Regenerate Static files.

Adding and updating regenerates the files, but you can always regenerate the static files (eg. if you updated your static assets or templates) by using:

blog --generate

Publishing

To publish the blog, you need to have rsync installed and pass the address (eg. youruser@yourserver.com:/path/to/blog)

blog --publish <remote_server>

You can also publish the archive of posts as a gemlog by passing a valid rsync target

blog --publish-archive <remote_server>

Source Control

Blog supports saving snapshots of the blog in git, and you can add and remove remotes with the following commands:

blog --add-remote <git_url>
blog --remove-remote

If a remote is present, it will be pulled before adding or updating, and pushed after it finishes. You can manually trigger this by calling

blog --sync-up
blog --sync-down

The blog will always sync down before adding to avoid going out of sync.

IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR CHANGES WILL BE LOST

Using Custom Templates

Blog comes with built-in templates that are quite generic and likely won't fit your use case. You can override these templates by creating a templates directory inside your blog data root ($XDG_DATA_HOME/blog).

For the ephemeral blog you can create feed.xml, index.html, and index.txt inside of templates. These files are then parsed with dot and passed the following variables:

it.posts <Array<Post>>

Post
 +id <String>        // The numerical timestamp when the blog post was added.
 +createdOn <String> // The UTC String of post creation date. (only feed.xml)
 +title <String>     // The title of the post. (only feed.xml)
 +raw <String>       // The raw gemini text of the template.
 +html <String>      // The parsed html generated from the gemini.

To customize your gemini archive you can provide an index.gmi file that will be used as a template for the archive. However the data structure is different, as it's just the gemini URL strings:

it.posts <Array<String>>

Using Static Files

Any files inside the static directory of your blog data root ($XDG_DATA_HOME/blog) will be copied as is. This is useful for any images, javascript files or stylesheets that you use in your posts or templates.

Configuration

You can control the number of posts in the ephemeral blog, and the location of configuration files using environment variables.

Overriding Number of Posts

Updating the BLOG_MAX_POSTS environment variable sets the number of posts that will be kept.

Overriding Configuration Directory

You can set the BLOG_CONFIG_DIRECTORY to any directory you want. This defaults to $XDG_CONFIG_HOME/blog/ and is used to store the blog remote config.

Overriding Data Directory

Setting BLOG_DATA_DIRECTORY will update where the posts, archive, static files, and templates are saved. The default is the $XDG_DATA_HOME/blog.

Overriding the location of generated files.

Setting BLOG_OUTPUT_DIRECTORY will update where generated files are placed.

The default is $XDG_CACHE_HOME/blog.

Debugging

If you want to know more about what's going on when blog generates data, set the environment variable NODE_DEBUG=blog. This will enable the debug messages