]> git.r.bdr.sh - rbdr/r.bdr.sh/blobdiff - blog.gmi
Add page descriptions
[rbdr/r.bdr.sh] / blog.gmi
index 323e1566b429d66c748547c8d3cbae2482ef35cb..6a3d0eb91d28bbb9bdd47eded608f441a72667b6 100644 (file)
--- a/blog.gmi
+++ b/blog.gmi
@@ -4,12 +4,46 @@
 
 Command line tool to author and manage a semi-ephemeral™ blog with a gemini archive.
 
 
 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
+=> https://git.r.bdr.sh/rbdr/blog ⧇ source
+=> https://git.sr.ht/~rbdr/blog ⧉ mirror
 
 ## Install
 
 
 ## 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.
+### Homebrew
+
+You can install using homebrew.
+
+```
+% brew tap rbdr/apps git@git.sr.ht:~rbdr/homebrew-apps
+% brew install rbdr/apps/blog
+```
+
+### Prebuilt Packages
+You can find pre-built packages for linux @ build.r.bdr.sh. There you can
+find a `.tar.gz` that includes only the binary, or `.rpm` and `.deb`
+distributions for fedora and debian that include a manpage.
+
+Binaries are provided for x86_64 and aarch64.
+
+Unstable releases are built directly from the main branch, while tagged
+versions have their own release and can be considered more stable.
+
+=> gemini://build.r.bdr.sh/blog blog pre-built releases @ gemini
+=> https://build.r.bdr.sh/blog blog pre-built releases @ https
+
+### 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
 
 
 ## Usage I: Authoring
 
@@ -19,7 +53,7 @@ Create a `.gmi` gemini file.
 
 You can add this to the blog using the following command:
 ```
 
 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.
 ```
 
 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.
@@ -29,7 +63,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:
 
 ```
 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.
 ```
 
 This will replace the latest with the contents of the `path` without shifting the existing entries. It will also regenerate files.
@@ -39,10 +73,10 @@ 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):
 
 ```
 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
+## II: Publishing
 
 Publishing the blog and archive requires `rsync`.
 
 
 Publishing the blog and archive requires `rsync`.
 
@@ -51,7 +85,7 @@ Publishing the blog and archive requires `rsync`.
 You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog)
 
 ```
 You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog)
 
 ```
-blog --publish <remote_server>
+blog publish <remote_server>
 ```
 
 This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog.
 ```
 
 This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog.
@@ -61,32 +95,32 @@ 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
 
 ```
 You can also publish the archive of posts as a gemlog by passing a valid rsync target
 
 ```
-blog --publish-archive <remote_server>
+blog publish-archive <remote_server>
 ```
 
 This will include *all the posts* in gemtext format.
 
 ```
 
 This will include *all the posts* in gemtext format.
 
-## Usage III: Source Control
+## III: 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:
 
 ```
-blog --add-remote <git_url>
-blog --remove-remote
+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
 
 ```
 ```
 
 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.
 
 **IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR CHANGES WILL BE LOST**
 
 ```
 
 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
+## 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:
 
 
 The default templates included in blog are very generic and likely not helpful for your use case. However, you can customize this freely:
 
@@ -97,27 +131,65 @@ 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:
 
 ```
 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>>
+posts <Array<Post>>       // The array of posts
+has_posts <Boolean>       // Whether the posts array has any posts or not
+posts_length <Integer>    // The number of posts in the posts array
+
+Post
+ +id <String>             // The id of the post
+ +created_on <String>     // The numerical timestamp when the blog post was added
+ +created_on_utc <String> // The RFC-2822 String of post creation date
+ +title <String>          // The title of the post
+ +raw <String>            // The raw gemini text of the template
+ +html <String>           // The parsed html generated from the gemini
+ +escaped_html <String>   // 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 <Array<ArchivePost>>  // The array of posts
+archive_length <Integer>    // The number of archive posts in the 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.
+ +id <String>               // The id of the post
+ +slug <String>             // The slug of the post (used to generate URLs)
+ +title <String>            // 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 <Array<String>>
+{{~ posts: post }}
+{{= post.html}}
+{{~}}
 ```
 
 ```
 
+Finally, you can do conditionals. To negate a conditional you can prepend !.
+
+```
+{{# !has_posts }}
+<p> There are no posts </p>
+{{#}}
+```
+
+=> 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.
 
 ### 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?
+## V: Where is Data Stored?
 
 Blog uses three diretories to store data, all of them using the XDG User
 Directories.
 
 Blog uses three diretories to store data, all of them using the XDG User
 Directories.
@@ -130,7 +202,7 @@ Directories.
 
 All of these can be overridden by environment variables.
 
 
 All of these can be overridden by environment variables.
 
-## Usage VI: Configuration
+## VI: Configuration
 
 You can control the number of posts in the ephemeral blog, and the location of
 all the data by using environment variables.
 
 You can control the number of posts in the ephemeral blog, and the location of
 all the data by using environment variables.
@@ -159,7 +231,11 @@ The default is `$XDG_CACHE_HOME/blog`.
 
 ## Changelog
 
 
 ## Changelog
 
+* 7.0.0 Rewritten in rust, supports gopher (geomyidae format).
 * 6.0.0 Use custom templates, use XDG directories.
 * 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
 * 5.0.2 Internal template changes
 * 5.0.1 Dependency update
 * 5.0.0 Publish using rsync instead of s3