git.r.bdr.sh - rbdr/r.bdr.sh/blob - blog_6.0.0.gmi

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