Make smaller

[rbdr/blog] / README.md

diff --git a/README.md b/README.md
index a598cb068d40535e103a19f080e11dc2cce937c3..061800a06d2700eb197124156a53f6d5ad382e52 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,15 +1,28 @@
 # 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
+
+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.
 
 
 Create a `.gmi` gemini file.
 


@@ -24,7 +37,9 @@ 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
+
+If you need to make corrections to the latest entry, use:

 
 ```
 blog --update path/to/blog_post.gmi
 
 ```
 blog --update path/to/blog_post.gmi


@@ -33,25 +48,33 @@ 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.
 

-You can always regenerate the static files by using
+### 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
 ```
 
 
 ```
 blog --generate
 ```
 

-To publish the blog, you can select an s3 bucket and run it with:
+### Publishing
+
+To publish the blog, you need to have `rsync` installed and pass the address
+(eg. youruser@yourserver.com:/path/to/blog)

 
 ```
 
 ```

-blog --publish <bucket>
+blog --publish <remote_server>

 ```
 
 ```
 

-You can also publish the archive of posts as a gemlog, by passing a valid
+You can also publish the archive of posts as a gemlog by passing a valid

 rsync target
 
 ```
 rsync target
 
 ```

-blog --publish-archive <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 supports saving snapshots of the blog in git, and you can add and remove
 remotes with the following commands:
 


@@ -68,67 +91,72 @@ blog --sync-up
 blog --sync-down
 ```
 
 blog --sync-down
 ```
 

-## Configuring
-
-### Overriding Number of Posts
+The blog will always sync down before adding to avoid going out of sync.

 
 

-Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
-that will be kept.
+**IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR
+CHANGES WILL BE LOST**

 
 

-### Overriding Templates
+### Using Custom 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.
+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`).

 
 

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

 ```
 
 ```
 

-The default is the `templates` directory inside the root of the `blog`
-module directory.
+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:

 
 

-### Overriding the location of posts.
+```
+it.posts <Array<String>>
+```

 
 

-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.
+### Using Static Files

 
 

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

 
 

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

 
 

-The default is the `static` directory inside the root of the `blog` module
-directory.
+You can control the number of posts in the ephemeral blog, and the location of
+configuration files using environment variables.

 
 

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

 
 

-## How to publish
+Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
+that will be kept.

 
 

-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 Configuration Directory

 
 

-## The archive
+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`.

 
 

-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