Remove unnecessary static files

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

If you need to make corrections use:

```
blog --update path/to/blog_post.gmi
```

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

You can always regenerate the static files by using

```
blog --generate
```

To publish the blog, you can select an s3 bucket and run it with:

```
blog --publish <bucket>
```

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

```
blog --publish-archive <rsync_target>
```

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

## Configuring

### 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, static files, and template

The tool will expect a `feed.xml`, `index.html`, and `index.txt` files in the
`templates` directory inside the config directory. If they're not found it will
default to the included tepmlates.

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

### Overriding the location of posts.

Setting `BLOG_DATA_DIRECTORY` will update where the posts and archive are saved
when added. 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`.

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/