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 Templates
  79
  80 You can set the `BLOG_TEMPLATES_DIRECTORY` to any directory you want.
  81 The tool will expect a `feed.xml`, `index.html`, and `index.txt` files.
  82
  83 These templates are then parsed with [dot][dot] and exposes the following
  84 variables:
  85
  86 ```
  87 it.posts: <Array[Post]>
  88
  89 Post
  90  +id: String        // The numerical timestamp when the blog post was added.
  91  +createdOn: String // The UTC String of post creation date. (only feed.xml)
  92  +title: String     // The title of the post. (only feed.xml)
  93  +raw: String       // The raw gemini text of the template.
  94  +html: String      // The parsed html generated from the gemini.
  95 ```
  96
  97 The default is the `templates` directory inside the root of the `blog`
  98 module directory.
  99
 100 ### Overriding the location of posts.
 101
 102 Setting `BLOG_POSTS_DIRECTORY` will update where the posts are saved when
 103 added. The default is the `.posts` directory inside the root of the
 104 `blog` module directory.
 105
 106 ### Overriding the location of static files.
 107
 108 Setting `BLOG_STATIC_DIRECTORY` will update where static files are read
 109 from. This is also where the generated blog will be placed.
 110
 111 The default is the `static` directory inside the root of the `blog` module
 112 directory.
 113
 114 This directory should also contain files referenced in the templates, like
 115 `css`, `js` or `images`.
 116
 117 ## How to publish
 118
 119 The publishing method is extremely naive. It assumes you have the
 120 AWS CLI installed and configured. It will attempt to sync the static
 121 directory to the bucket.
 122
 123 ## The archive
 124
 125 The archive directory will have a full archive of the posts (currently
 126 as a gemlog format).
 127
 128 This gets updated every time you add or update a post.
 129
 130 Publishing with `--publish` will not publish the archive. Instead you should
 131 use `--publish-archive`, which will `rsync` it to the destination provided.
 132
 133 ## Debugging
 134
 135 If you want to know more about what's going on when blog generates
 136 data, set the environment variable `NODE_DEBUG=blog`. This will
 137 enable the debug messages
 138
 139 [dot]: https://olado.github.io/doT/