]> git.r.bdr.sh - rbdr/blog/blame_incremental - README.md
Add deb generator
[rbdr/blog] / README.md
... / ...
CommitLineData
1# blog
2
3Blog is a tool to create a semi-ephemeralâ„¢ blog with a "permanent" archive
4on gemini.
5
6## The Ephemeral Blog.
7
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.
10
11Posts will disappear as you add new ones.
12
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
26
27Create a `.gmi` gemini file.
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
33```
34blog --add path/to/blog_post.gmi
35```
36
37These commands will regenerate the static files. At that point you can
38preview your blog by serving the files on the `static` directory.
39
40### How to update the latest entry
41
42If you need to make corrections to the latest entry, use:
43
44```
45blog --update path/to/blog_post.gmi
46```
47
48This will replace the latest with the contents of the `path` without
49shifting the existing entries.
50
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:
55
56```
57blog --generate
58```
59
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)
64
65```
66blog --publish <remote_server>
67```
68
69You can also publish the archive of posts as a gemlog by passing a valid
70rsync target
71
72```
73blog --publish-archive <remote_server>
74```
75
76### Source Control
77
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```
93
94The blog will always sync down before adding to avoid going out of sync.
95
96**IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR
97CHANGES WILL BE LOST**
98
99### Using Custom Templates
100
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`).
104
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:
108
109```
110it.posts <Array<Post>>
111
112Post
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.
118```
119
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:
123
124```
125it.posts <Array<String>>
126```
127
128### Using Static Files
129
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.
133
134## Configuration
135
136You can control the number of posts in the ephemeral blog, and the location of
137configuration files using environment variables.
138
139### Overriding Number of Posts
140
141Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
142that will be kept.
143
144### Overriding Configuration Directory
145
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.
149
150### Overriding Data Directory
151
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`.
160
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
167[dot]: https://olado.github.io/doT/