Add rudimentary sync support

[rbdr/blog] / README.md

diff --git a/README.md b/README.md
index 47137302da81ce2f8dc010920da3dd8d56336b32..41de942a8eff1d8757a347dc90960ff30f553b2d 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,14 +38,76 @@ 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.
 
-Will publish the blog.
+This directory should also contain files referenced in the templates, like
+`css`, `js` or `images`.
 
 ## How to publish
 
-At the moment, the app does not include any publishers. [surge][surge] is an easy
-way to do it, just point it to your static directory.
+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
 
-[surge]: https://surge.sh
+[dot]: https://olado.github.io/doT/