💾 Archived View for r.bdr.sh › blog.gmi captured on 2024-07-08 at 23:45:18. Gemini links have been rewritten to link to archived content

View Raw

More Information

⬅️ Previous capture (2024-03-21)

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

Blog

Command line tool to author and manage a semi-ephemeral™ blog with a gemini archive.

view source @ git.r.bdr.sh

source mirror @ sourcehut

Install

Homebrew

You can install using homebrew.

% brew tap rbdr/apps git@git.sr.ht:~rbdr/homebrew-apps
% brew install rbdr/apps/blog

Prebuilt Packages

You can find pre-built packages for linux @ build.r.bdr.sh. There you can

find a `.tar.gz` that includes only the binary, or `.rpm` and `.deb`

distributions for fedora and debian that include a manpage.

Binaries are provided for x86_64 and aarch64.

Unstable releases are built directly from the main branch, while tagged

versions have their own release and can be considered more stable.

blog pre-built releases @ gemini

blog pre-built releases @ https

From Source

Make sure you have rust and Make installed. Clone the repository, and run:

% make -e profile=release

Then copy the file somewhere in your PATH

% cp ./target/release/blog /usr/local/bin

Usage I: Authoring

Add a New Post

Create a `.gmi` gemini file.

You can add this to the blog using the following command:

blog add path/to/blog_post.gmi

This it will shift all posts and remove the oldest one if the limit of posts is reached (defualts to 3). This will also regenerate the static files.

Updating the Latest post

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

blog update path/to/blog_post.gmi

This will replace the latest with the contents of the `path` without shifting the existing entries. It will also regenerate files.

Regenerate Static files.

Adding and updating posts regenerates the blog and archive, but you can always regenerate manually (eg. if you updated your static assets or templates):

blog generate

Usage II: Publishing

Publishing the blog and archive requires `rsync`.

Publishing the Blog

You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog)

blog publish <remote_server>

This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog.

Publishing the Archive

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

blog publish-archive <remote_server>

This will include *all the posts* in gemtext format.

Usage III: 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.

Usage IV: Customizing

The default templates included in blog are very generic and likely not helpful for your use case. However, you can customize this freely:

Using Custom Templates

You can override the default 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][dot] and passed the following variables:

posts <Array<Post>>       // The array of posts
has_posts <Boolean>       // Whether the posts array has any posts or not
posts_length <Integer>    // The number of posts in the posts array

Post
 +id <String>             // The id of the post
 +created_on <String>     // The numerical timestamp when the blog post was added
 +created_on_utc <String> // The RFC-2822 String of post creation date
 +title <String>          // The title of the post
 +raw <String>            // The raw gemini text of the template
 +html <String>           // The parsed html generated from the gemini
 +escaped_html <String>   // Same as html, but escaped for inclusion in XML

To customize your gemini and gopher archives you can provide an `index.gmi` and `index.gph` files that will be used as templates for the archive. However the data structure is different:

posts <Array<ArchivePost>>  // The array of posts
archive_length <Integer>    // The number of archive posts in the posts array

Post
 +id <String>               // The id of the post
 +slug <String>             // The slug of the post (used to generate URLs)
 +title <String>            // The title of the post

The Template Syntax

The template is a subset of DoT. You can print values, iterate over arrays, or check conditionals. The template does not allow expressions. You can only reference keys in the structure above.

You can print values

{{= posts.raw }}

You can iterate over collections. With the format COLLECTION: MEMBER, where MEMBER will become part of the template below, and the template will be repeated for each member of COLLECTION.

{{~ posts: post }}
{{= post.html}}
{{~}}

Finally, you can do conditionals. To negate a conditional you can prepend !.

{{# !has_posts }}
<p> There are no posts </p>
{{#}}

DoT template language.

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.

Usage V: Where is Data Stored?

Blog uses three diretories to store data, all of them using the XDG User

Directories.

XDG User Directories.

- Configuration is stored in $XDG_CONFIG_HOME/blog

- Data such as the raw blog, templates, and static files are stored in $XDG_DATA_HOME/blog

- Generated "ready to upload" files are stored in $XDG_CACHE_HOME/blog

All of these can be overridden by environment variables.

Usage VI: Configuration

You can control the number of posts in the ephemeral blog, and the location of

all the data by 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`.

Changelog

Deprecated documentation for blog 6.0.0