]> git.r.bdr.sh - rbdr/blog/blame - README.md
Ignore errors on checkout
[rbdr/blog] / README.md
CommitLineData
4ae55e06 1# blog
7a5a585e 2
fac54389
RBR
3Blog at unlimited.pizza -> Only 3 at a time.*
4
5The blog is no longer 100% ephemeral. Instead it now keeps an archive
6in a separate folder. The archive is intended to be used as a gemlog.
7a5a585e
BB
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
fac54389 14Create a directory with a `.gmi` gemini file, and an `/assets`
7a5a585e
BB
15directory with anything you want in there. This can be in any directory.
16
17```
18.
19└── this-is-an-example-post
20 ├── assets
fac54389 21 │   └── example.wav
7a5a585e
BB
22 └── this-is-an-example-post.md
23```
24
25You can add this to the blog using the following command, it will shift
26all 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
31These commands will regenerate the static files. At that point you can
d92ac8cc 32preview your blog by serving the files on the `static` directory.
7a5a585e
BB
33
34If you need to make corrections use:
35
36`blog --update path/to/blog_post`
37
38This will replace the latest with the contents of the `path` without
39shifting the existing entries.
40
fac54389
RBR
41`blog --publish <bucket>`
42
43Will publish the blog to the mentioned s3 bucket.
44
45## Configuring
46
47### Overriding Number of Posts
48
49Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
50that will be kept.
51
52### Overriding Templates
53
54You can set the `BLOG_TEMPLATES_DIRECTORY` to any directory you want.
55The tool will expect a `feed.xml`, `index.html`, and `index.txt` files.
56
57These templates are then parsed with [dot][dot] and exposes the following
58variables:
59
60```
61it.posts: <Array[Post]>
62
63Post
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
71The default is the `templates` directory inside the root of the `blog`
72module directory.
73
74### Overriding the location of posts.
75
76Setting `BLOG_POSTS_DIRECTORY` will update where the posts are saved when
77added. The default is the `.posts` directory inside the root of the
78`blog` module directory.
79
80### Overriding the location of static files.
81
82Setting `BLOG_STATIC_DIRECTORY` will update where static files are read
83from. This is also where the generated blog will be placed.
84
85The default is the `static` directory inside the root of the `blog` module
86directory.
7a5a585e 87
fac54389
RBR
88This directory should also contain files referenced in the templates, like
89`css`, `js` or `images`.
39744467
BB
90
91## How to publish
92
fac54389
RBR
93The publishing method is extremely naive. It assumes you have the
94AWS CLI installed and configured. It will attempt to sync the static
95directory to the bucket.
96
97## The archive
98
99The archive directory will have a full archive of the posts (currently
100as a gemlog format).
101
102This gets updated every time you add or update a post.
103
65d379f5
RBR
104Publishing with `--publish` will not publish the archive. Instead you should
105use `--publish-archive`, which will `rsync` it to the destination provided.
39744467 106
d92ac8cc
BB
107## Debugging
108
109If you want to know more about what's going on when blog generates
110data, set the environment variable `NODE_DEBUG=blog`. This will
111enable the debug messages
112
fac54389 113[dot]: https://olado.github.io/doT/