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