Update blog documentation

diff --git a/blog.gmi b/blog.gmi
index fa0c90b0a7de7ee3259bdc585a3acb76e88304e7..dce90df03806be35e92121c6c6333765d4c8d9d3 100644 (file)
--- 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
 
 
 ## 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
 
 
 ## Usage I: Authoring
 


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


@@ -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:
 
 ```
 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.


@@ -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):
 
 ```
 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
 ```
 
 ## 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)
 
 ```
 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.


@@ -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
 
 ```
 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.


@@ -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 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.
 ```
 
 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:
 
 ```
 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.


@@ -166,6 +219,9 @@ The default is `$XDG_CACHE_HOME/blog`.
 ## Changelog
 
 * 6.0.0 Use custom templates, use XDG directories.
 ## 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
 * 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 (file)
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 <remote_server>
+```
+
+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 <remote_server>
+```
+
+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 <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**
+
+## 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 <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>>
+```
+
+### 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