git.r.bdr.sh - rbdr/blog/blob - README.md

   1 # blog
   2
   3 Blog is a tool to create a semi-ephemeral™ blog with a "permanent" archive
   4 on gemini.
   5
   6 ## The Ephemeral Blog.
   7
   8 Whenever you generate your blog, it will keep only the first 3 files and
   9 render an html page, an rss feed and a plaintext file.
  10
  11 Posts will disappear as you add new ones.
  12
  13 ## The archive
  14
  15 Not everything is ephemeral, as we also generate an archive of the whole
  16 blog in gemini format.
  17
  18 ## Installation
  19
  20 At the moment only installation from source is available. Clone this repository
  21 and run `pnpm install -g .`. This will add the `blog` command to your shell.
  22
  23 ## Usage
  24
  25 ### How to add a new entry
  26
  27 Create a `.gmi` gemini file.
  28
  29 You can add this to the blog using the following command, it will shift
  30 all entries and remove the oldest one if limit of posts is reached
  31 (defualts to 3):
  32
  33 ```
  34 blog --add path/to/blog_post.gmi
  35 ```
  36
  37 These commands will regenerate the static files. At that point you can
  38 preview your blog by serving the files on the `static` directory.
  39
  40 ### How to update the latest entry
  41
  42 If you need to make corrections to the latest entry, use:
  43
  44 ```
  45 blog --update path/to/blog_post.gmi
  46 ```
  47
  48 This will replace the latest with the contents of the `path` without
  49 shifting the existing entries.
  50
  51 ### Regenerate Static files.
  52
  53 Adding and updating regenerates the files, but you can always regenerate
  54 the static files (eg. if you updated your static assets or templates) by using:
  55
  56 ```
  57 blog --generate
  58 ```
  59
  60 ### Publishing
  61
  62 To publish the blog, you need to have `rsync` installed and pass the address
  63 (eg. youruser@yourserver.com:/path/to/blog)
  64
  65 ```
  66 blog --publish <remote_server>
  67 ```
  68
  69 You can also publish the archive of posts as a gemlog by passing a valid
  70 rsync target
  71
  72 ```
  73 blog --publish-archive <remote_server>
  74 ```
  75
  76 ### Source Control
  77
  78 Blog supports saving snapshots of the blog in git, and you can add and remove
  79 remotes with the following commands:
  80
  81 ```
  82 blog --add-remote <git_url>
  83 blog --remove-remote
  84 ```
  85
  86 If a remote is present, it will be pulled before adding or updating, and pushed
  87 after it finishes. You can manually trigger this by calling
  88
  89 ```
  90 blog --sync-up
  91 blog --sync-down
  92 ```
  93
  94 The blog will always sync down before adding to avoid going out of sync.
  95
  96 **IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR
  97 CHANGES WILL BE LOST**
  98
  99 ### Using Custom Templates
 100
 101 Blog comes with built-in templates that are quite generic and likely won't
 102 fit your use case. You can override these templates by creating a `templates`
 103 directory inside your blog data root (`$XDG_DATA_HOME/blog`).
 104
 105 For the ephemeral blog you can create `feed.xml`, `index.html`, and
 106 `index.txt` inside of `templates`. These files are then parsed with [dot][dot]
 107 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
 121 be used as a template for the archive. However the data structure is different,
 122 as it's just the gemini URL strings:
 123
 124 ```
 125 it.posts <Array<String>>
 126 ```
 127
 128 ### Using Static Files
 129
 130 Any files inside the `static` directory of your blog data root
 131 (`$XDG_DATA_HOME/blog`) will be copied as is. This is useful for any images,
 132 javascript files or stylesheets that you use in your posts or templates.
 133
 134 ## Configuration
 135
 136 You can control the number of posts in the ephemeral blog, and the location of
 137 configuration files using environment variables.
 138
 139 ### Overriding Number of Posts
 140
 141 Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
 142 that will be kept.
 143
 144 ### Overriding Configuration Directory
 145
 146 You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
 147 defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
 148 config.
 149
 150 ### Overriding Data Directory
 151
 152 Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
 153 files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
 154
 155 ### Overriding the location of generated files.
 156
 157 Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
 158
 159 The default is `$XDG_CACHE_HOME/blog`.
 160
 161 ## Debugging
 162
 163 If you want to know more about what's going on when blog generates
 164 data, set the environment variable `NODE_DEBUG=blog`. This will
 165 enable the debug messages
 166
 167 [dot]: https://olado.github.io/doT/