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