Add manual file

[rbdr/blog] / README.md

diff --git a/README.md b/README.md
index 41de942a8eff1d8757a347dc90960ff30f553b2d..061800a06d2700eb197124156a53f6d5ad382e52 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,108 +1,162 @@
 # blog
 
 # blog
 

-Blog at unlimited.pizza -> Only 3 at a time.*
+Blog is a tool to create a semi-ephemeral™ blog with a "permanent" archive
+on gemini.

 
 

-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.
+## The Ephemeral Blog.

 
 

-## How to install
+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.

 
 

-`npm install -g .` will expose the `blog` binary to your CLI.
+Posts will disappear as you add new ones.

 
 

-## How to add a new entry
+## The archive

 
 

-Create a directory with a `.gmi` gemini file, and an `/assets`
-directory with anything you want in there. This can be in any directory.
+Not everything is ephemeral, as we also generate an archive of the whole
+blog in gemini format.

 
 

-```
-.
-└── this-is-an-example-post
-    ├── assets
-    │   └── example.wav
-    └── this-is-an-example-post.md
-```
+## 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):
 
 
 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.
 
 
 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:
+### How to update the latest entry

 
 

-`blog --update path/to/blog_post`
+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.
 
 
 This will replace the latest with the contents of the `path` without
 shifting the existing entries.
 

-`blog --publish <bucket>`
+### Regenerate Static files.

 
 

-Will publish the blog to the mentioned s3 bucket.
+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:

 
 

-## Configuring
+```
+blog --generate
+```

 
 

-### Overriding Number of Posts
+### Publishing

 
 

-Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
-that will be kept.
+To publish the blog, you need to have `rsync` installed and pass the address
+(eg. youruser@yourserver.com:/path/to/blog)

 
 

-### Overriding Templates
+```
+blog --publish <remote_server>
+```
+
+You can also publish the archive of posts as a gemlog by passing a valid
+rsync target

 
 

-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.
+```
+blog --publish-archive <remote_server>
+```

 
 

-These templates are then parsed with [dot][dot] and exposes the following
-variables:
+### 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

 ```
 ```

-it.posts: <Array[Post]>
+
+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
 
 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.
+ +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>>

 ```
 
 ```
 

-The default is the `templates` directory inside the root of the `blog`
-module directory.
+### Using Static Files

 
 

-### Overriding the location of posts.
+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.

 
 

-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.
+## Configuration

 
 

-### Overriding the location of static files.
+You can control the number of posts in the ephemeral blog, and the location of
+configuration files using environment variables.

 
 

-Setting `BLOG_STATIC_DIRECTORY` will update where static files are read
-from. This is also where the generated blog will be placed.
+### Overriding Number of Posts

 
 

-The default is the `static` directory inside the root of the `blog` module
-directory.
+Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
+that will be kept.

 
 

-This directory should also contain files referenced in the templates, like
-`css`, `js` or `images`.
+### Overriding Configuration Directory

 
 

-## How to publish
+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.

 
 

-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.
+### Overriding Data Directory

 
 

-## The archive
+Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
+files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.

 
 

-The archive directory will have a full archive of the posts (currently
-as a gemlog format).
+### Overriding the location of generated files.

 
 

-This gets updated every time you add or update a post.
+Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.

 
 

-Publishing with `--publish` will not publish the archive. Instead you should
-use `--publish-archive`, which will `rsync` it to the destination provided.
+The default is `$XDG_CACHE_HOME/blog`.

 
 ## Debugging
 
 
 ## Debugging