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 directory with a `.gmi` gemini file, and an `/assets`
  15 directory with anything you want in there. This can be in any directory.
  16
  17 ```
  18 .
  19 └── this-is-an-example-post
  20     ├── assets
  21     │   └── example.wav
  22     └── this-is-an-example-post.md
  23 ```
  24
  25 You can add this to the blog using the following command, it will shift
  26 all entries and remove the oldest one if limit of posts is reached
  27 (defualts to 3):
  28
  29 `blog --add path/to/blog_post`
  30
  31 These commands will regenerate the static files. At that point you can
  32 preview your blog by serving the files on the `static` directory.
  33
  34 If you need to make corrections use:
  35
  36 `blog --update path/to/blog_post`
  37
  38 This will replace the latest with the contents of the `path` without
  39 shifting the existing entries.
  40
  41 `blog --publish <bucket>`
  42
  43 Will publish the blog to the mentioned s3 bucket.
  44
  45 ## Configuring
  46
  47 ### Overriding Number of Posts
  48
  49 Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
  50 that will be kept.
  51
  52 ### Overriding Templates
  53
  54 You can set the `BLOG_TEMPLATES_DIRECTORY` to any directory you want.
  55 The tool will expect a `feed.xml`, `index.html`, and `index.txt` files.
  56
  57 These templates are then parsed with [dot][dot] and exposes the following
  58 variables:
  59
  60 ```
  61 it.posts: <Array[Post]>
  62
  63 Post
  64  +id: String        // The numerical timestamp when the blog post was added.
  65  +createdOn: String // The UTC String of post creation date. (only feed.xml)
  66  +title: String     // The title of the post. (only feed.xml)
  67  +raw: String       // The raw gemini text of the template.
  68  +html: String      // The parsed html generated from the gemini.
  69 ```
  70
  71 The default is the `templates` directory inside the root of the `blog`
  72 module directory.
  73
  74 ### Overriding the location of posts.
  75
  76 Setting `BLOG_POSTS_DIRECTORY` will update where the posts are saved when
  77 added. The default is the `.posts` directory inside the root of the
  78 `blog` module directory.
  79
  80 ### Overriding the location of static files.
  81
  82 Setting `BLOG_STATIC_DIRECTORY` will update where static files are read
  83 from. This is also where the generated blog will be placed.
  84
  85 The default is the `static` directory inside the root of the `blog` module
  86 directory.
  87
  88 This directory should also contain files referenced in the templates, like
  89 `css`, `js` or `images`.
  90
  91 ## How to publish
  92
  93 The publishing method is extremely naive. It assumes you have the
  94 AWS CLI installed and configured. It will attempt to sync the static
  95 directory to the bucket.
  96
  97 ## The archive
  98
  99 The archive directory will have a full archive of the posts (currently
 100 as a gemlog format).
 101
 102 This gets updated every time you add or update a post.
 103
 104 The publishing will not publish the archive. This is up to you to control.
 105
 106 ## Debugging
 107
 108 If you want to know more about what's going on when blog generates
 109 data, set the environment variable `NODE_DEBUG=blog`. This will
 110 enable the debug messages
 111
 112 [dot]: https://olado.github.io/doT/