From: Ruben Beltran del Rio Date: Sat, 9 Mar 2024 15:14:13 +0000 (+0100) Subject: Update blog documentation X-Git-Url: https://git.r.bdr.sh/rbdr/r.bdr.sh/commitdiff_plain/6626b64f0d1d643b170384f6eed8b97704f43338 Update blog documentation --- diff --git a/blog.gmi b/blog.gmi index fa0c90b..dce90df 100644 --- a/blog.gmi +++ b/blog.gmi @@ -9,13 +9,28 @@ Command line tool to author and manage a semi-ephemeral™ blog with a gemini ar ## Install -At the moment only installation from source is available. Clone this repository and run: +### Homebrew + +You can install using homebrew. ``` -pnpm install -g . +% brew tap rbdr/apps git@git.sr.ht:~rbdr/homebrew-apps +% brew install rbdr/apps/blog ``` -This will add the `blog` command to your shell. +### From Source + +Make sure you have rust and Make installed. Clone the repository, and run: + +``` +% make -e profile=release +``` + +Then copy the file somewhere in your PATH + +``` +% cp ./target/release/blog /usr/local/bin +``` ## Usage I: Authoring @@ -25,7 +40,7 @@ Create a `.gmi` gemini file. You can add this to the blog using the following command: ``` -blog --add path/to/blog_post.gmi +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. @@ -35,7 +50,7 @@ This it will shift all posts and remove the oldest one if the limit of posts is If you need to make corrections to the latest post, use: ``` -blog --update path/to/blog_post.gmi +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. @@ -45,7 +60,7 @@ This will replace the latest with the contents of the `path` without shifting th 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 +blog generate ``` ## Usage II: Publishing @@ -57,7 +72,7 @@ Publishing the blog and archive requires `rsync`. You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog) ``` -blog --publish +blog publish ``` This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog. @@ -67,7 +82,7 @@ This publishes the static files, including the html index, rss feed and plaintex You can also publish the archive of posts as a gemlog by passing a valid rsync target ``` -blog --publish-archive +blog publish-archive ``` This will include *all the posts* in gemtext format. @@ -77,15 +92,15 @@ 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 -blog --remove-remote +blog add-remote +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 +blog sync-up +blog sync-down ``` The blog will always sync down before adding to avoid going out of sync. @@ -103,22 +118,60 @@ You can override the default templates by creating a `templates` directory insid 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 > +posts > // The array of posts +has_posts // Whether the posts array has any posts or not +posts_length // The number of posts in the posts array + +Post + +id // The id of the post + +created_on // The numerical timestamp when the blog post was added + +created_on_utc // The RFC-2822 String of post creation date + +title // The title of the post + +raw // The raw gemini text of the template + +html // The parsed html generated from the gemini + +escaped_html // Same as html, but escaped for inclusion in XML +``` + +To customize your gemini and gopher archives you can provide an `index.gmi` and `index.gph` files that will be used as templates for the archive. However the data structure is different: + +``` +posts > // The array of posts +archive_length // The number of archive posts in the posts array Post - +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. + +id // The id of the post + +slug // The slug of the post (used to generate URLs) + +title // The title of the post +``` + +### The Template Syntax + +The template is a subset of DoT. You can print values, iterate over arrays, or check conditionals. The template does not allow expressions. You can only reference keys in the structure above. + +You can print values + +``` +{{= posts.raw }} ``` -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: +You can iterate over collections. With the format COLLECTION: MEMBER, where MEMBER will become part of the template below, and the template will be repeated for each member of COLLECTION. ``` -it.posts > +{{~ posts: post }} +{{= post.html}} +{{~}} ``` +Finally, you can do conditionals. To negate a conditional you can prepend !. + +``` +{{# !has_posts }} +

There are no posts

+{{#}} +``` + +=> https://olado.github.io/doT/index.html DoT template language. + ### 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. @@ -166,6 +219,9 @@ The default is `$XDG_CACHE_HOME/blog`. ## Changelog * 6.0.0 Use custom templates, use XDG directories. + +=> ./blog_6.0.0.gmi Deprecated documentation for blog 6.0.0 + * 5.0.2 Internal template changes * 5.0.1 Dependency update * 5.0.0 Publish using rsync instead of s3 diff --git a/blog_6.0.0.gmi b/blog_6.0.0.gmi new file mode 100644 index 0000000..3a7a9a0 --- /dev/null +++ b/blog_6.0.0.gmi @@ -0,0 +1,180 @@ +--- title: /blog-6.0.0.html +--- description: Documentation for deprecated blog 6.0.0, a tool to author and manage a semi-ephemeral™ blog with a gemini archive. +## Blog (6.0.0) + +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]. + +=> ./blog.gmi [1] Main documentation for blog + +Command line tool to author and manage a semi-ephemeral™ blog with a gemini archive. + +=> https://git.r.bdr.sh/rbdr/blog view source @ git.r.bdr.sh +=> https://git.sr.ht/~rbdr/blog source mirror @ sourcehut + +## Install + +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 I: Authoring + +### Add a New Post + +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. + +### Updating the Latest post + +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. + +### Regenerate Static 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 +``` + +## Usage II: Publishing + +Publishing the blog and archive requires `rsync`. + +### Publishing the Blog + +You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog) + +``` +blog --publish +``` + +This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog. + +### Publishing the Archive + +You can also publish the archive of posts as a gemlog by passing a valid rsync target + +``` +blog --publish-archive +``` + +This will include *all the posts* in gemtext format. + +## Usage III: 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 +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** + +## Usage IV: Customizing + +The default templates included in blog are very generic and likely not helpful for your use case. However, you can customize this freely: + +### Using Custom Templates + +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 > + +Post + +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. +``` + +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 > +``` + +### 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. + +## Usage V: Where is Data Stored? + +Blog uses three diretories to store data, all of them using the XDG User +Directories. + +=> https://wiki.archlinux.org/title/XDG_user_directories 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. + +## Usage VI: Configuration + +You can control the number of posts in the ephemeral blog, and the location of +all the data by 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`. + +## Changelog + +* 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