-- Leo's gemini proxy
-- Connecting to r.bdr.sh:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini; lang=en
NOTE: This documentation is for the deprecated javascript-based blog 6.0.0. For the newer blog, you should go to the main documentation[1].
Command line tool to author and manage a semi-ephemeral™ blog with a gemini archive.
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.
Create a `.gmi` gemini file.
You can add this to the blog using the following command:
blog --add path/to/blog_post.gmi
This it will shift all posts and remove the oldest one if the limit of posts is reached (defualts to 3). This will also regenerate the static files.
If you need to make corrections to the latest post, use:
blog --update path/to/blog_post.gmi
This will replace the latest with the contents of the `path` without shifting the existing entries. It will also regenerate files.
Adding and updating posts regenerates the blog and archive, but you can always regenerate manually (eg. if you updated your static assets or templates):
blog --generate
Publishing the blog and archive requires `rsync`.
You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog)
blog --publish <remote_server>
This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog.
You can also publish the archive of posts as a gemlog by passing a valid rsync target
blog --publish-archive <remote_server>
This will include *all the posts* in gemtext format.
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**
The default templates included in blog are very generic and likely not helpful for your use case. However, you can customize this freely:
You can override the default 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>>
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.
Blog uses three diretories to store data, all of them using the XDG User
Directories.
- Configuration is stored in $XDG_CONFIG_HOME/blog
- Data such as the raw blog, templates, and static files are stored in $XDG_DATA_HOME/blog
- Generated "ready to upload" files are stored in $XDG_CACHE_HOME/blog
All of these can be overridden by environment variables.
You can control the number of posts in the ephemeral blog, and the location of
all the data by using environment variables.
Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
that will be kept.
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.
Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
The default is `$XDG_CACHE_HOME/blog`.
6.0.0 Use custom templates, use XDG directories.
5.0.2 Internal template changes
5.0.1 Dependency update
5.0.0 Publish using rsync instead of s3
4.0.0 Add gemini archive
3.0.0 Add support for RSS and TXT
2.0.0 Add support for S3 publishing
1.0.1 Bugs and dependency fixes
1.0.0 Initial release
-- Response ended
-- Page fetched on Mon May 20 21:49:11 2024