git.r.bdr.sh - rbdr/r.bdr.sh/blob - blog.gmi

   1 --- title: /blog.html
   2 --- description: Blog is a command-line tool to author and manage a semi-ephemeral™ blog with a gemini archive.
   3 ## Blog
   4
   5 Command line tool to author and manage a semi-ephemeral™ blog with a gemini archive.
   6
   7 => https://git.r.bdr.sh/rbdr/blog view source @ git.r.bdr.sh
   8 => https://git.sr.ht/~rbdr/blog source mirror @ sourcehut
   9
  10 ## Install
  11
  12 ### Homebrew
  13
  14 You can install using homebrew.
  15
  16 ```
  17 % brew tap rbdr/apps git@git.sr.ht:~rbdr/homebrew-apps
  18 % brew install rbdr/apps/blog
  19 ```
  20
  21 ### From Source
  22
  23 Make sure you have rust and Make installed. Clone the repository, and run:
  24
  25 ```
  26 % make -e profile=release
  27 ```
  28
  29 Then copy the file somewhere in your PATH
  30
  31 ```
  32 % cp ./target/release/blog /usr/local/bin
  33 ```
  34
  35 ## Usage I: Authoring
  36
  37 ### Add a New Post
  38
  39 Create a `.gmi` gemini file.
  40
  41 You can add this to the blog using the following command:
  42 ```
  43 blog add path/to/blog_post.gmi
  44 ```
  45
  46 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.
  47
  48 ### Updating the Latest post
  49
  50 If you need to make corrections to the latest post, use:
  51
  52 ```
  53 blog update path/to/blog_post.gmi
  54 ```
  55
  56 This will replace the latest with the contents of the `path` without shifting the existing entries. It will also regenerate files.
  57
  58 ### Regenerate Static files.
  59
  60 Adding and updating posts regenerates the blog and archive, but you can always regenerate manually (eg. if you updated your static assets or templates):
  61
  62 ```
  63 blog generate
  64 ```
  65
  66 ## Usage II: Publishing
  67
  68 Publishing the blog and archive requires `rsync`.
  69
  70 ### Publishing the Blog
  71
  72 You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog)
  73
  74 ```
  75 blog publish <remote_server>
  76 ```
  77
  78 This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog.
  79
  80 ### Publishing the Archive
  81
  82 You can also publish the archive of posts as a gemlog by passing a valid rsync target
  83
  84 ```
  85 blog publish-archive <remote_server>
  86 ```
  87
  88 This will include *all the posts* in gemtext format.
  89
  90 ## Usage III: Source Control
  91
  92 Blog supports saving snapshots of the blog in git, and you can add and remove remotes with the following commands:
  93
  94 ```
  95 blog add-remote <git_url>
  96 blog remove-remote
  97 ```
  98
  99 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
 100
 101 ```
 102 blog sync-up
 103 blog sync-down
 104 ```
 105
 106 The blog will always sync down before adding to avoid going out of sync.
 107
 108 **IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR CHANGES WILL BE LOST**
 109
 110 ## Usage IV: Customizing
 111
 112 The default templates included in blog are very generic and likely not helpful for your use case. However, you can customize this freely:
 113
 114 ### Using Custom Templates
 115
 116 You can override the default templates by creating a `templates` directory inside your blog data root (`$XDG_DATA_HOME/blog`).
 117
 118 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:
 119
 120 ```
 121 posts <Array<Post>>       // The array of posts
 122 has_posts <Boolean>       // Whether the posts array has any posts or not
 123 posts_length <Integer>    // The number of posts in the posts array
 124
 125 Post
 126  +id <String>             // The id of the post
 127  +created_on <String>     // The numerical timestamp when the blog post was added
 128  +created_on_utc <String> // The RFC-2822 String of post creation date
 129  +title <String>          // The title of the post
 130  +raw <String>            // The raw gemini text of the template
 131  +html <String>           // The parsed html generated from the gemini
 132  +escaped_html <String>   // Same as html, but escaped for inclusion in XML
 133 ```
 134
 135 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:
 136
 137 ```
 138 posts <Array<ArchivePost>>  // The array of posts
 139 archive_length <Integer>    // The number of archive posts in the posts array
 140
 141 Post
 142  +id <String>               // The id of the post
 143  +slug <String>             // The slug of the post (used to generate URLs)
 144  +title <String>            // The title of the post
 145 ```
 146
 147 ### The Template Syntax
 148
 149 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.
 150
 151 You can print values
 152
 153 ```
 154 {{= posts.raw }}
 155 ```
 156
 157 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.
 158
 159 ```
 160 {{~ posts: post }}
 161 {{= post.html}}
 162 {{~}}
 163 ```
 164
 165 Finally, you can do conditionals. To negate a conditional you can prepend !.
 166
 167 ```
 168 {{# !has_posts }}
 169 <p> There are no posts </p>
 170 {{#}}
 171 ```
 172
 173 => https://olado.github.io/doT/index.html DoT template language.
 174
 175 ### Using Static Files
 176
 177 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.
 178
 179 ## Usage V: Where is Data Stored?
 180
 181 Blog uses three diretories to store data, all of them using the XDG User
 182 Directories.
 183
 184 => https://wiki.archlinux.org/title/XDG_user_directories XDG User Directories.
 185
 186 - Configuration is stored in $XDG_CONFIG_HOME/blog
 187 - Data such as the raw blog, templates, and static files are stored in $XDG_DATA_HOME/blog
 188 - Generated "ready to upload" files are stored in $XDG_CACHE_HOME/blog
 189
 190 All of these can be overridden by environment variables.
 191
 192 ## Usage VI: Configuration
 193
 194 You can control the number of posts in the ephemeral blog, and the location of
 195 all the data by using environment variables.
 196
 197 ### Overriding Number of Posts
 198
 199 Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
 200 that will be kept.
 201
 202 ### Overriding Configuration Directory
 203
 204 You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
 205 defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
 206 config.
 207
 208 ### Overriding Data Directory
 209
 210 Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
 211 files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
 212
 213 ### Overriding the location of generated files.
 214
 215 Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
 216
 217 The default is `$XDG_CACHE_HOME/blog`.
 218
 219 ## Changelog
 220
 221 * 6.0.0 Use custom templates, use XDG directories.
 222
 223 => ./blog_6.0.0.gmi Deprecated documentation for blog 6.0.0
 224
 225 * 5.0.2 Internal template changes
 226 * 5.0.1 Dependency update
 227 * 5.0.0 Publish using rsync instead of s3
 228 * 4.0.0 Add gemini archive
 229 * 3.0.0 Add support for RSS and TXT
 230 * 2.0.0 Add support for S3 publishing
 231 * 1.0.1 Bugs and dependency fixes
 232 * 1.0.0 Initial release