]> git.r.bdr.sh - rbdr/blog/blame - README.md
Missing comma
[rbdr/blog] / README.md
CommitLineData
4ae55e06 1# blog
7a5a585e 2
0307770b
RBR
3Blog is a tool to create a semi-ephemeral™ blog with a "permanent" archive
4on gemini.
fac54389 5
0307770b 6## The Ephemeral Blog.
7a5a585e 7
0307770b
RBR
8Whenever you generate your blog, it will keep only the first 3 files and
9render an html page, an rss feed and a plaintext file.
7a5a585e 10
0307770b 11Posts will disappear as you add new ones.
7a5a585e 12
0307770b
RBR
13## The archive
14
15Not everything is ephemeral, as we also generate an archive of the whole
16blog in gemini format.
17
18## Installation
19
20At the moment only installation from source is available. Clone this repository
21and run `pnpm install -g .`. This will add the `blog` command to your shell.
22
23## Usage
24
25### How to add a new entry
7a5a585e 26
2acbdb03 27Create a `.gmi` gemini file.
7a5a585e
BB
28
29You can add this to the blog using the following command, it will shift
30all entries and remove the oldest one if limit of posts is reached
31(defualts to 3):
32
2acbdb03
RBR
33```
34blog --add path/to/blog_post.gmi
35```
7a5a585e
BB
36
37These commands will regenerate the static files. At that point you can
d92ac8cc 38preview your blog by serving the files on the `static` directory.
7a5a585e 39
0307770b
RBR
40### How to update the latest entry
41
42If you need to make corrections to the latest entry, use:
7a5a585e 43
2acbdb03
RBR
44```
45blog --update path/to/blog_post.gmi
46```
7a5a585e
BB
47
48This will replace the latest with the contents of the `path` without
49shifting the existing entries.
50
0307770b
RBR
51### Regenerate Static files.
52
53Adding and updating regenerates the files, but you can always regenerate
54the static files (eg. if you updated your static assets or templates) by using:
fac54389 55
2acbdb03
RBR
56```
57blog --generate
58```
59
0307770b
RBR
60### Publishing
61
62To publish the blog, you need to have `rsync` installed and pass the address
63(eg. youruser@yourserver.com:/path/to/blog)
2acbdb03
RBR
64
65```
0307770b 66blog --publish <remote_server>
2acbdb03
RBR
67```
68
0307770b 69You can also publish the archive of posts as a gemlog by passing a valid
2acbdb03
RBR
70rsync target
71
72```
0307770b 73blog --publish-archive <remote_server>
2acbdb03
RBR
74```
75
0307770b
RBR
76### Source Control
77
2acbdb03
RBR
78Blog supports saving snapshots of the blog in git, and you can add and remove
79remotes with the following commands:
80
81```
82blog --add-remote <git_url>
83blog --remove-remote
84```
85
86If a remote is present, it will be pulled before adding or updating, and pushed
87after it finishes. You can manually trigger this by calling
88
89```
90blog --sync-up
91blog --sync-down
92```
fac54389 93
0307770b 94The blog will always sync down before adding to avoid going out of sync.
fac54389 95
0307770b
RBR
96**IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR
97CHANGES WILL BE LOST**
fac54389 98
0307770b 99### Using Custom Templates
6cd62e79 100
0307770b
RBR
101Blog comes with built-in templates that are quite generic and likely won't
102fit your use case. You can override these templates by creating a `templates`
103directory inside your blog data root (`$XDG_DATA_HOME/blog`).
fac54389 104
0307770b
RBR
105For the ephemeral blog you can create `feed.xml`, `index.html`, and
106`index.txt` inside of `templates`. These files are then parsed with [dot][dot]
107and passed the following variables:
fac54389
RBR
108
109```
0307770b 110it.posts <Array<Post>>
fac54389
RBR
111
112Post
0307770b
RBR
113 +id <String> // The numerical timestamp when the blog post was added.
114 +createdOn <String> // The UTC String of post creation date. (only feed.xml)
115 +title <String> // The title of the post. (only feed.xml)
116 +raw <String> // The raw gemini text of the template.
117 +html <String> // The parsed html generated from the gemini.
fac54389
RBR
118```
119
0307770b
RBR
120To customize your gemini archive you can provide an `index.gmi` file that will
121be used as a template for the archive. However the data structure is different,
122as it's just the gemini URL strings:
fac54389 123
0307770b
RBR
124```
125it.posts <Array<String>>
126```
fac54389 127
0307770b 128### Using Static Files
fac54389 129
0307770b
RBR
130Any files inside the `static` directory of your blog data root
131(`$XDG_DATA_HOME/blog`) will be copied as is. This is useful for any images,
132javascript files or stylesheets that you use in your posts or templates.
fac54389 133
0307770b 134## Configuration
7a5a585e 135
0307770b
RBR
136You can control the number of posts in the ephemeral blog, and the location of
137configuration files using environment variables.
39744467 138
0307770b 139### Overriding Number of Posts
39744467 140
0307770b
RBR
141Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
142that will be kept.
fac54389 143
0307770b 144### Overriding Configuration Directory
fac54389 145
0307770b
RBR
146You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
147defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
148config.
fac54389 149
0307770b 150### Overriding Data Directory
fac54389 151
0307770b
RBR
152Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
153files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
154
155### Overriding the location of generated files.
156
157Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
158
159The default is `$XDG_CACHE_HOME/blog`.
39744467 160
d92ac8cc
BB
161## Debugging
162
163If you want to know more about what's going on when blog generates
164data, set the environment variable `NODE_DEBUG=blog`. This will
165enable the debug messages
166
fac54389 167[dot]: https://olado.github.io/doT/