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