]> git.r.bdr.sh - rbdr/blog/blob - man/blog.1
Add manual file
[rbdr/blog] / man / blog.1
1 .TH BLOG 1 "2024-03-12" "7.0.0" "Blog Manual"
2 .SH NAME
3 blog \- ephemeral blog authoring tool with gemini and gopher archive.
4 .SH SYNOPSIS
5 .B blog
6 \ COMMAND [\fIARGUMENT\fP\]
7 .SH DESCRIPTION
8 .PP
9 blog is a tool that lets you manage an ephemeral blog via https, and keep a
10 non-ephemeral archive in gemini and gopher. By default, the blog will only
11 keep 3 posts, but you can adjust this by setting the
12 .B BLOG_OUTPUT_DIRECTORY
13 environment variable.
14 .SH COMMANDS
15 .TP
16 .B "help "
17 Display help.
18 .TP
19 .B version
20 Display version information.
21 .TP
22 .B "status "
23 Display status of your blog.
24 .TP
25 \fBadd\fR \fIFILE\fR
26 Adds a new blog post at position 0
27 .TP
28 \fBupdate\fR \fIFILE\fR
29 Update the blog post at position 0
30 .TP
31 .B generate
32 Generates the static assets for the blog and archive
33 .TP
34 \fBpublish\fR \fIREMOTE_HOST\fR
35 Copies the files for the ephemeral blog to REMOTE_HOST. (eg. username@host:/path/to/remote)
36 .TP
37 \fBpublish-archive\fR \fIREMOTE_HOST\fR
38 Copies the files for the permanent archive to REMOTE_HOST. (eg. username@host:/path/to/remote)
39 .TP
40 \fBadd-remote\fR \fIGIT_URL\fR
41 Adds or updates a git remote to sync the blog contents
42 .TP
43 .B remove-remote
44 Removes the git remote associated with the blog
45 .TP
46 .B sync-up
47 Pushes to the git remote. This will force a push.
48 .TP
49 .B sync-down
50 Gets the files from the blog. This will erase any local changes.
51 .SH ENVIRONMENT VARIABLES
52 You can configure some aspects of the blog using environment variables
53 .TP
54 .B BLOG_MAX_POSTS
55 Sets the maximum number of posts. Defaults to 3.
56 .TP
57 .B BLOG_CONFIG_DIRECTORY
58 Sets the location for configuration. Defaults to \fI$XDG_CONFIG_HOME/blog\fR.
59 .TP
60 .B BLOG_DATA_DIRECTORY
61 Sets the location for the main blog data: posts, archive, templates, and static
62 files. Defaults to \fI$XDG_DATA_HOME/blog\fR.
63 .TP
64 .B BLOG_OUTPUT_DIRECTORY
65 Sets the location for the generated static files ready to be published.
66 Defaults to \fI$XDG_CACHE_HOME/blog\fR.
67 .SH TEMPLATES
68 You can override the default templates by creating a \fItemplates\fR directory
69 inside your blog data root (\fBXDG_DATA_HOME/blog\fR).
70
71 For the ephemeral blog you can create \fIfeed.xml\fR, \fIindex.html\fR, and
72 \fIindex.txt\fR inside of \fItemplates\fR. These files are then parsed with
73 the following values.
74
75 .TP
76 .I posts
77 A collection of posts
78 .TP
79 .I has_posts
80 Whether the posts array has any posts or not (boolean)
81 .TP
82 .I posts_length
83 The number of posts in the posts array
84
85 .P
86 Each post in the posts collection has the following fields.
87
88 .TP
89 .I id
90 The id of the post
91 .TP
92 .I created_on
93 The numerical timestamp when the blog post was added
94 .TP
95 .I created_on_utc
96 The RFC-2822 String of post creation date
97 .TP
98 .I title
99 The title of the post
100 .TP
101 .I raw
102 The raw gemini text of the template
103 .TP
104 .I html
105 The parsed html generated from the gemini
106 .TP
107 .I escaped_html
108 Same as html, but escaped for inclusion in XML
109
110 .P
111 To customize your gemini and gopher archives you can provide an \fIindex.gmi\fR
112 and \fIindex.gph\fR files that will be used as templates for the archive.
113 However the data structure is different.
114
115 .TP
116 .I posts
117 A collection of archive posts
118 .TP
119 .I archive_length
120 The number of archive posts in the posts array
121
122 .P
123 Each post in the archive has the following fields
124
125 .TP
126 .I id
127 The id of the post
128 .TP
129 .I slug
130 The slug of the post (used to generate URLs)
131 .TP
132 .I title
133 The title of the post
134 .SH TEMPLATE SYNTAX
135 The template is a subset of DoT. You can print values, iterate over collections,
136 or check conditionals. The template does not allow expressions. You can only
137 reference keys in the structure above.
138
139 You can print values
140
141 \f(CW
142 {{= posts.raw }}
143 \fR
144
145 You can iterate over collections. With the format COLLECTION: MEMBER, where
146 MEMBER will become part of the template below, and the template will be
147 repeated for each member of COLLECTION.
148 .nf
149 \f(CW
150 {{~ posts: post }}
151 {{= post.html}}
152 {{~}}
153 \fR
154 .fi
155 Finally, you can do conditionals. To negate a conditional you can prepend !.
156 .nf
157 \f(CW
158 {{# !has_posts }}
159 <p> There are no posts </p>
160 {{#}}
161 \fR
162 .fi
163 .SH STATIC FILES
164 Any files inside the \fIstatic\fR directory of your blog data root
165 (\fBXDG_DATA_HOME/blog\fR) will be copied as is. This is useful for any images,
166 javascript files or stylesheets that you use in your posts or templates.
167 .SH VERSION
168 .BR 7.0.0
169 .SH HOMEPAGE
170 .I https://r.bdr.sh/blog.html
171 .SH AUTHORS
172 \ Rubén Beltrán del Río <\fIblog@r.bdr.sh\fP>