]> git.r.bdr.sh - rbdr/r.bdr.sh/blob - blog_6.0.0.gmi
Change heading sizes
[rbdr/r.bdr.sh] / blog_6.0.0.gmi
1 --- title: /blog-6.0.0.html
2 --- description: Documentation for deprecated blog 6.0.0, a tool to author and manage a semi-ephemeralâ„¢ blog with a gemini archive.
3 ## Blog (6.0.0)
4
5 NOTE: This documentation is for the deprecated javascript-based blog 6.0.0. For the newer blog, you should go to the main documentation[1].
6
7 => ./blog.gmi [1] Main documentation for blog
8
9 Command line tool to author and manage a semi-ephemeralâ„¢ blog with a gemini archive.
10
11 => https://git.r.bdr.sh/rbdr/blog view source @ git.r.bdr.sh
12 => https://git.sr.ht/~rbdr/blog source mirror @ sourcehut
13
14 ## Install
15
16 At the moment only installation from source is available. Clone this repository and run:
17
18 ```
19 pnpm install -g .
20 ```
21
22 This will add the `blog` command to your shell.
23
24 ## Usage I: Authoring
25
26 ### Add a New Post
27
28 Create a `.gmi` gemini file.
29
30 You can add this to the blog using the following command:
31 ```
32 blog --add path/to/blog_post.gmi
33 ```
34
35 This it will shift all posts and remove the oldest one if the limit of posts is reached (defualts to 3). This will also regenerate the static files.
36
37 ### Updating the Latest post
38
39 If you need to make corrections to the latest post, use:
40
41 ```
42 blog --update path/to/blog_post.gmi
43 ```
44
45 This will replace the latest with the contents of the `path` without shifting the existing entries. It will also regenerate files.
46
47 ### Regenerate Static files.
48
49 Adding and updating posts regenerates the blog and archive, but you can always regenerate manually (eg. if you updated your static assets or templates):
50
51 ```
52 blog --generate
53 ```
54
55 ## Usage II: Publishing
56
57 Publishing the blog and archive requires `rsync`.
58
59 ### Publishing the Blog
60
61 You can publish to any valid `rsync` target (eg. ruben@coolserver.local:blog)
62
63 ```
64 blog --publish <remote_server>
65 ```
66
67 This publishes the static files, including the html index, rss feed and plaintext version of the ephemeral blog.
68
69 ### Publishing the Archive
70
71 You can also publish the archive of posts as a gemlog by passing a valid rsync target
72
73 ```
74 blog --publish-archive <remote_server>
75 ```
76
77 This will include *all the posts* in gemtext format.
78
79 ## Usage III: Source Control
80
81 Blog supports saving snapshots of the blog in git, and you can add and remove remotes with the following commands:
82
83 ```
84 blog --add-remote <git_url>
85 blog --remove-remote
86 ```
87
88 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
89
90 ```
91 blog --sync-up
92 blog --sync-down
93 ```
94
95 The blog will always sync down before adding to avoid going out of sync.
96
97 **IF YOU CHANGE ANY FILES MANUALLY, REMEMBER TO SYNC UP, OTHERWISE YOUR CHANGES WILL BE LOST**
98
99 ## Usage IV: Customizing
100
101 The default templates included in blog are very generic and likely not helpful for your use case. However, you can customize this freely:
102
103 ### Using Custom Templates
104
105 You can override the default templates by creating a `templates` directory inside your blog data root (`$XDG_DATA_HOME/blog`).
106
107 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:
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 be used as a template for the archive. However the data structure is different, as it's just the gemini URL strings:
121
122 ```
123 it.posts <Array<String>>
124 ```
125
126 ### Using Static Files
127
128 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.
129
130 ## Usage V: Where is Data Stored?
131
132 Blog uses three diretories to store data, all of them using the XDG User
133 Directories.
134
135 => https://wiki.archlinux.org/title/XDG_user_directories XDG User Directories.
136
137 - Configuration is stored in $XDG_CONFIG_HOME/blog
138 - Data such as the raw blog, templates, and static files are stored in $XDG_DATA_HOME/blog
139 - Generated "ready to upload" files are stored in $XDG_CACHE_HOME/blog
140
141 All of these can be overridden by environment variables.
142
143 ## Usage VI: Configuration
144
145 You can control the number of posts in the ephemeral blog, and the location of
146 all the data by using environment variables.
147
148 ### Overriding Number of Posts
149
150 Updating the `BLOG_MAX_POSTS` environment variable sets the number of posts
151 that will be kept.
152
153 ### Overriding Configuration Directory
154
155 You can set the `BLOG_CONFIG_DIRECTORY` to any directory you want. This
156 defaults to `$XDG_CONFIG_HOME/blog/` and is used to store the blog remote
157 config.
158
159 ### Overriding Data Directory
160
161 Setting `BLOG_DATA_DIRECTORY` will update where the posts, archive, static
162 files, and templates are saved. The default is the `$XDG_DATA_HOME/blog`.
163
164 ### Overriding the location of generated files.
165
166 Setting `BLOG_OUTPUT_DIRECTORY` will update where generated files are placed.
167
168 The default is `$XDG_CACHE_HOME/blog`.
169
170 ## Changelog
171
172 * 6.0.0 Use custom templates, use XDG directories.
173 * 5.0.2 Internal template changes
174 * 5.0.1 Dependency update
175 * 5.0.0 Publish using rsync instead of s3
176 * 4.0.0 Add gemini archive
177 * 3.0.0 Add support for RSS and TXT
178 * 2.0.0 Add support for S3 publishing
179 * 1.0.1 Bugs and dependency fixes
180 * 1.0.0 Initial release