Escape ampersand in titles

[rbdr/blog] / README.md

diff --git a/README.md b/README.md
index 47137302da81ce2f8dc010920da3dd8d56336b32..a598cb068d40535e103a19f080e11dc2cce937c3 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,41 +11,129 @@ Blog at unlimited.pizza -> Only
 
 ## How to add a new entry
 
-Create a directory with a `.md` markdown 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
-    └── this-is-an-example-post.md
-```
+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`
+```
+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. 
+preview your blog by serving the files on the `static` directory.
 
 If you need to make corrections use:
 
-`blog --update path/to/blog_post`
+```
+blog --update path/to/blog_post.gmi
+```
 
 This will replace the latest with the contents of the `path` without
 shifting the existing entries.
 
-`blog --publish`
+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:
 
-Will publish the blog.
+```
+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
 
-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/