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 At the moment only installation from source is available. Clone this repository and run:
  13
  14 ```
  15 pnpm install -g .
  16 ```
  17
  18 This will add the `blog` command to your shell.
  19
  20 ## Usage I: Authoring
  21
  22 ### Add a New Post
  23
  24 Create a `.gmi` gemini file.
  25
  26 You can add this to the blog using the following command:
  27 ```
  28 blog --add path/to/blog_post.gmi
  29 ```
  30
  31 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.
  32
  33 ### Updating the Latest post
  34
  35 If you need to make corrections to the latest post, use:
  36
  37 ```
  38 blog --update path/to/blog_post.gmi
  39 ```
  40
  41 This will replace the latest with the contents of the `path` without shifting the existing entries. It will also regenerate files.
  42
  43 ### Regenerate Static files.
  44
  45 Adding and updating posts regenerates the blog and archive, but you can always regenerate manually (eg. if you updated your static assets or templates):
  46
  47 ```
  48 blog --generate
  49 ```
  50
  51 ## Usage II: Publishing
  52
  53 Publishing the blog and archive requires `rsync`.
  54
  55 ### Publishing the Blog
  56
  57 You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog)
  58
  59 ```
  60 blog --publish <remote_server>
  61 ```
  62
  63 This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog.
  64
  65 ### Publishing the Archive
  66
  67 You can also publish the archive of posts as a gemlog by passing a valid rsync target
  68
  69 ```
  70 blog --publish-archive <remote_server>
  71 ```
  72
  73 This will include *all the posts* in gemtext format.
  74
  75 ## Usage III: Source Control
  76
  77 Blog supports saving snapshots of the blog in git, and you can add and remove remotes with the following commands:
  78
  79 ```
  80 blog --add-remote <git_url>
  81 blog --remove-remote
  82 ```
  83
  84 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
  85
  86 ```
  87 blog --sync-up
  88 blog --sync-down
  89 ```
  90
  91 The blog will always sync down before adding to avoid going out of sync.
  92
  93 **IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR CHANGES WILL BE LOST**
  94
  95 ## Usage IV: Customizing
  96
  97 The default templates included in blog are very generic and likely not helpful for your use case. However, you can customize this freely:
  98
  99 ### Using Custom Templates
 100
 101 You can override the default templates by creating a `templates` directory inside your blog data root (`$XDG_DATA_HOME/blog`).
 102
 103 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:
 104
 105 ```
 106 it.posts <Array<Post>>
 107
 108 Post
 109  +id <String>        // The numerical timestamp when the blog post was added.
 110  +createdOn <String> // The UTC String of post creation date. (only feed.xml)
 111  +title <String>     // The title of the post. (only feed.xml)
 112  +raw <String>       // The raw gemini text of the template.
 113  +html <String>      // The parsed html generated from the gemini.
 114 ```
 115
 116 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:
 117
 118 ```
 119 it.posts <Array<String>>
 120 ```
 121
 122 ### Using Static Files
 123
 124 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.
 125
 126 ## Usage V: Where is Data Stored?
 127
 128 Blog uses three diretories to store data, all of them using the XDG User
 129 Directories.
 130
 131 => https://wiki.archlinux.org/title/XDG_user_directories XDG User Directories.
 132
 133 - Configuration is stored in $XDG_CONFIG_HOME/blog
 134 - Data such as the raw blog, templates, and static files are stored in $XDG_DATA_HOME/blog
 135 - Generated "ready to upload" files are stored in $XDG_CACHE_HOME/blog
 136
 137 All of these can be overridden by environment variables.
 138
 139 ## Usage VI: Configuration
 140
 141 You can control the number of posts in the ephemeral blog, and the location of
 142 all the data by using environment variables.
 143
 144 ### Overriding Number of Posts
 145
 146 Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
 147 that will be kept.
 148
 149 ### Overriding Configuration Directory
 150
 151 You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
 152 defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
 153 config.
 154
 155 ### Overriding Data Directory
 156
 157 Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
 158 files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
 159
 160 ### Overriding the location of generated files.
 161
 162 Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
 163
 164 The default is `$XDG_CACHE_HOME/blog`.
 165
 166 ## Changelog
 167
 168 * 6.0.0 Use custom templates, use XDG directories.
 169 * 5.0.2 Internal template changes
 170 * 5.0.1 Dependency update
 171 * 5.0.0 Publish using rsync instead of s3
 172 * 4.0.0 Add gemini archive
 173 * 3.0.0 Add support for RSS and TXT
 174 * 2.0.0 Add support for S3 publishing
 175 * 1.0.1 Bugs and dependency fixes
 176 * 1.0.0 Initial release