Add rudimentary gemlog archive support

[rbdr/blog] / README.md

diff --git a/README.md b/README.md
index 7f7903ab8c57a2a02288312db37cfe9db0334a44..d0c4eb12ce88bf296036de493e6ca94e205e7201 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,6 +1,9 @@
 # blog
 
-Blog at unlimited.pizza -> Only 
+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
 
@@ -8,14 +11,14 @@ Blog at unlimited.pizza -> Only
 
 ## How to add a new entry
 
-Create a directory with a `.md` markdown file, and an `/assets`
+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.png
+    │   └── example.wav
     └── this-is-an-example-post.md
 ```
 
@@ -26,7 +29,7 @@ all entries and remove the oldest one if limit of posts is reached
 `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. 
+preview your blog by serving the files on the `static` directory.
 
 If you need to make corrections use:
 
@@ -35,6 +38,75 @@ If you need to make corrections use:
 This will replace the latest with the contents of the `path` without
 shifting the existing entries.
 
-`blog --publish`
+`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.
+
+The publishing will not publish the archive. This is up to you to control.
+
+## 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
 
-Will publish the blog.
+[dot]: https://olado.github.io/doT/