Force use main

[rbdr/blog] / README.md

diff --git a/README.md b/README.md
index 2634854dd4ec037996a2c2b1ccf78d2b40e52431..41de942a8eff1d8757a347dc90960ff30f553b2d 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,2 +1,113 @@
 # blog
-A temporary 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/