]> git.r.bdr.sh - rbdr/blog/blob - README.md
Fixes for remote setup
[rbdr/blog] / 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 Publishing with `--publish` will not publish the archive. Instead you should
105 use `--publish-archive`, which will `rsync` it to the destination provided.
106
107 ## Debugging
108
109 If you want to know more about what's going on when blog generates
110 data, set the environment variable `NODE_DEBUG=blog`. This will
111 enable the debug messages
112
113 [dot]: https://olado.github.io/doT/