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

   1 # blog
   2
   3 Blog at unlimited.pizza -> Only 3 at a time.
   4
   5 The blog is no longer 100% ephemeral. Instead it now keeps an archive
   6 in a separate folder. The archive is intended to be used as a gemlog.
   7
   8 ## How to install
   9
  10 `npm install -g .` will expose the `blog` binary to your CLI.
  11
  12 ## How to add a new entry
  13
  14 Create a `.gmi` gemini file.
  15
  16 You can add this to the blog using the following command, it will shift
  17 all entries and remove the oldest one if limit of posts is reached
  18 (defualts to 3):
  19
  20 ```
  21 blog --add path/to/blog_post.gmi
  22 ```
  23
  24 These commands will regenerate the static files. At that point you can
  25 preview your blog by serving the files on the `static` directory.
  26
  27 If you need to make corrections use:
  28
  29 ```
  30 blog --update path/to/blog_post.gmi
  31 ```
  32
  33 This will replace the latest with the contents of the `path` without
  34 shifting the existing entries.
  35
  36 You can always regenerate the static files by using
  37
  38 ```
  39 blog --generate
  40 ```
  41
  42 To publish the blog, you can select an s3 bucket and run it with:
  43
  44 ```
  45 blog --publish <bucket>
  46 ```
  47
  48 You can also publish the archive of posts as a gemlog, by passing a valid
  49 rsync target
  50
  51 ```
  52 blog --publish-archive <rsync_target>
  53 ```
  54
  55 Blog supports saving snapshots of the blog in git, and you can add and remove
  56 remotes with the following commands:
  57
  58 ```
  59 blog --add-remote <git_url>
  60 blog --remove-remote
  61 ```
  62
  63 If a remote is present, it will be pulled before adding or updating, and pushed
  64 after it finishes. You can manually trigger this by calling
  65
  66 ```
  67 blog --sync-up
  68 blog --sync-down
  69 ```
  70
  71 ## Configuring
  72
  73 ### Overriding Number of Posts
  74
  75 Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
  76 that will be kept.
  77
  78 ### Overriding Configuration Directory
  79
  80 You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
  81 defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
  82 config, static files, and template
  83
  84 The tool will expect a `feed.xml`, `index.html`, and `index.txt` files in the
  85 `templates` directory inside the config directory. If they're not found it will
  86 default to the included tepmlates.
  87
  88 These templates are then parsed with [dot][dot] and exposes the following
  89 variables:
  90
  91 ```
  92 it.posts: <Array[Post]>
  93
  94 Post
  95  +id: String        // The numerical timestamp when the blog post was added.
  96  +createdOn: String // The UTC String of post creation date. (only feed.xml)
  97  +title: String     // The title of the post. (only feed.xml)
  98  +raw: String       // The raw gemini text of the template.
  99  +html: String      // The parsed html generated from the gemini.
 100 ```
 101
 102 ### Overriding the location of posts.
 103
 104 Setting `BLOG_DATA_DIRECTORY` will update where the posts and archive are saved
 105 when added. The default is the `$XDG_DATA_HOME/blog`.
 106
 107 ### Overriding the location of generated files.
 108
 109 Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
 110
 111 The default is `$XDG_CACHE_HOME/blog`.
 112
 113 This directory should also contain files referenced in the templates, like
 114 `css`, `js` or `images`.
 115
 116 ## How to publish
 117
 118 The publishing method is extremely naive. It assumes you have the
 119 AWS CLI installed and configured. It will attempt to sync the static
 120 directory to the bucket.
 121
 122 ## The archive
 123
 124 The archive directory will have a full archive of the posts (currently
 125 as a gemlog format).
 126
 127 This gets updated every time you add or update a post.
 128
 129 Publishing with `--publish` will not publish the archive. Instead you should
 130 use `--publish-archive`, which will `rsync` it to the destination provided.
 131
 132 ## Debugging
 133
 134 If you want to know more about what's going on when blog generates
 135 data, set the environment variable `NODE_DEBUG=blog`. This will
 136 enable the debug messages
 137
 138 [dot]: https://olado.github.io/doT/