Escape ampersand in titles

[rbdr/blog] / README.md

diff --git a/README.md b/README.md
index 2634854dd4ec037996a2c2b1ccf78d2b40e52431..a598cb068d40535e103a19f080e11dc2cce937c3 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,2 +1,139 @@
 # 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 `.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 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/