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