Assorted fixes

[rbdr/blog] / README.md

# blog

Blog at unlimited.pizza -> Only 3 at a time.*

The blog is no longer 100% ephemeral. Instead it now keeps an archive
in a separate folder. The archive is intended to be used as a gemlog.

## How to install

`npm install -g .` will expose the `blog` binary to your CLI.

## How to add a new entry

Create a directory with a `.gmi` gemini file, and an `/assets`
directory with anything you want in there. This can be in any directory.

```
.
└── this-is-an-example-post
    ├── assets
    │   └── example.wav
    └── this-is-an-example-post.md
```

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`

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

If you need to make corrections use:

`blog --update path/to/blog_post`

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

`blog --publish <bucket>`

Will publish the blog to the mentioned s3 bucket.

## Configuring

### Overriding Number of Posts

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

### Overriding Templates

You can set the `BLOG_TEMPLATES_DIRECTORY` to any directory you want.
The tool will expect a `feed.xml`, `index.html`, and `index.txt` files.

These templates are then parsed with [dot][dot] and exposes 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.
```

The default is the `templates` directory inside the root of the `blog`
module directory.

### Overriding the location of posts.

Setting `BLOG_POSTS_DIRECTORY` will update where the posts are saved when
added. The default is the `.posts` directory inside the root of the
`blog` module directory.

### Overriding the location of static files.

Setting `BLOG_STATIC_DIRECTORY` will update where static files are read
from. This is also where the generated blog will be placed.

The default is the `static` directory inside the root of the `blog` module
directory.

This directory should also contain files referenced in the templates, like
`css`, `js` or `images`.

## How to publish

The publishing method is extremely naive. It assumes you have the
AWS CLI installed and configured. It will attempt to sync the static
directory to the bucket.

## The archive

The archive directory will have a full archive of the posts (currently
as a gemlog format).

This gets updated every time you add or update a post.

Publishing with `--publish` will not publish the archive. Instead you should
use `--publish-archive`, which will `rsync` it to the destination provided.

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

[dot]: https://olado.github.io/doT/