From: Ruben Beltran del Rio Date: Wed, 14 Feb 2024 22:02:51 +0000 (+0100) Subject: Update README.md X-Git-Tag: 6.0.0 X-Git-Url: https://git.r.bdr.sh/rbdr/blog/commitdiff_plain/0307770b088afcc207bc5d84c63f8b681db0aebf Update README.md --- diff --git a/README.md b/README.md index 2765c97..061800a 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,28 @@ # 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. @@ -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. -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 @@ -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. -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 ``` -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 +blog --publish ``` -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 ``` -blog --publish-archive +blog --publish-archive ``` +### Source Control + Blog supports saving snapshots of the blog in git, and you can add and remove remotes with the following commands: @@ -68,66 +91,72 @@ blog --sync-up 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 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, static files, and template +### Using Custom Templates -The tool will expect a `feed.xml`, `index.html`, and `index.txt` files in the -`templates` directory inside the config directory. If they're not found it will -default to the included tepmlates. +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: +it.posts > 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 // The numerical timestamp when the blog post was added. + +createdOn // The UTC String of post creation date. (only feed.xml) + +title // The title of the post. (only feed.xml) + +raw // The raw gemini text of the template. + +html // The parsed html generated from the gemini. ``` -### Overriding the location of posts. +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: -Setting `BLOG_DATA_DIRECTORY` will update where the posts and archive are saved -when added. The default is the `$XDG_DATA_HOME/blog`. +``` +it.posts > +``` -### Overriding the location of generated files. +### Using Static Files -Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed. +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. -The default is `$XDG_CACHE_HOME/blog`. +## Configuration -This directory should also contain files referenced in the templates, like -`css`, `js` or `images`. +You can control the number of posts in the ephemeral blog, and the location of +configuration files using environment variables. -## How to publish +### Overriding Number of Posts -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. +Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts +that will be kept. -## The archive +### Overriding Configuration Directory -The archive directory will have a full archive of the posts (currently -as a gemlog format). +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. -This gets updated every time you add or update a post. +### Overriding Data Directory -Publishing with `--publish` will not publish the archive. Instead you should -use `--publish-archive`, which will `rsync` it to the destination provided. +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