Update blog documentation

[rbdr/r.bdr.sh] / blog_6.0.0.gmi

--- title: /blog-6.0.0.html
--- description: Documentation for deprecated blog 6.0.0, a tool to author and manage a semi-ephemeral™ blog with a gemini archive.
## Blog (6.0.0)

NOTE: This documentation is for the deprecated javascript-based blog 6.0.0. For the newer blog, you should go to the main documentation[1].

=> ./blog.gmi [1] Main documentation for blog

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

=> https://git.r.bdr.sh/rbdr/blog view source @ git.r.bdr.sh
=> https://git.sr.ht/~rbdr/blog source mirror @ sourcehut

## Install

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 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.

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

## 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:

```
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.

## Usage V: Where is Data Stored?

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

=> https://wiki.archlinux.org/title/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

* 6.0.0 Use custom templates, use XDG directories.
* 5.0.2 Internal template changes
* 5.0.1 Dependency update
* 5.0.0 Publish using rsync instead of s3
* 4.0.0 Add gemini archive
* 3.0.0 Add support for RSS and TXT
* 2.0.0 Add support for S3 publishing
* 1.0.1 Bugs and dependency fixes
* 1.0.0 Initial release