X-Git-Url: https://git.r.bdr.sh/rbdr/blog/blobdiff_plain/4ae55e0673a61c50f1f7f378f6461d0388f66bd5..60307a9a3a39dccf652c9d9b4348e44db1e67627:/README.md?ds=sidebyside

diff --git a/README.md b/README.md
index 2634854..061800a 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,167 @@
 # blog
-A temporary blog
+
+Blog is a tool to create a semi-ephemeral™ blog with a "permanent" archive
+on gemini.
+
+## The Ephemeral Blog.
+
+Whenever you generate your blog, it will keep only the first 3 files and
+render an html page, an rss feed and a plaintext file.
+
+Posts will disappear as you add new ones.
+
+## The archive
+
+Not everything is ephemeral, as we also generate an archive of the whole
+blog in gemini format.
+
+## Installation
+
+At the moment only installation from source is available. Clone this repository
+and run `pnpm install -g .`. This will add the `blog` command to your shell.
+
+## Usage
+
+### 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.
+
+### How to update the latest entry
+
+If you need to make corrections to the latest entry, use:
+
+```
+blog --update path/to/blog_post.gmi
+```
+
+This will replace the latest with the contents of the `path` without
+shifting the existing entries.
+
+### Regenerate Static files.
+
+Adding and updating regenerates the files, but you can always regenerate
+the static files (eg. if you updated your static assets or templates) by using:
+
+```
+blog --generate
+```
+
+### Publishing
+
+To publish the blog, you need to have `rsync` installed and pass the address
+(eg. youruser@yourserver.com:/path/to/blog)
+
+```
+blog --publish <remote_server>
+```
+
+You can also publish the archive of posts as a gemlog by passing a valid
+rsync target
+
+```
+blog --publish-archive <remote_server>
+```
+
+### Source Control
+
+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
+```
+
+The blog will always sync down before adding to avoid going out of sync.
+
+**IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR
+CHANGES WILL BE LOST**
+
+### Using Custom Templates
+
+Blog comes with built-in templates that are quite generic and likely won't
+fit your use case. You can override these templates by creating a `templates`
+directory inside your blog data root (`$XDG_DATA_HOME/blog`).
+
+For the ephemeral blog you can create `feed.xml`, `index.html`, and
+`index.txt` inside of `templates`. These files are then parsed with [dot][dot]
+and passed 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.
+```
+
+To customize your gemini archive you can provide an `index.gmi` file that will
+be used as a template for the archive. However the data structure is different,
+as it's just the gemini URL strings:
+
+```
+it.posts <Array<String>>
+```
+
+### Using Static Files
+
+Any files inside the `static` directory of your blog data root
+(`$XDG_DATA_HOME/blog`) will be copied as is. This is useful for any images,
+javascript files or stylesheets that you use in your posts or templates.
+
+## Configuration
+
+You can control the number of posts in the ephemeral blog, and the location of
+configuration files using environment variables.
+
+### Overriding Number of Posts
+
+Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
+that will be kept.
+
+### Overriding Configuration Directory
+
+You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
+defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
+config.
+
+### Overriding Data Directory
+
+Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
+files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
+
+### Overriding the location of generated files.
+
+Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
+
+The default is `$XDG_CACHE_HOME/blog`.
+
+## 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/