Add manual file

[rbdr/blog] / man / blog.1

.TH BLOG 1 "2024-03-12" "7.0.0" "Blog Manual"
.SH NAME
blog \- ephemeral blog authoring tool with gemini and gopher archive.
.SH SYNOPSIS
.B blog
\ COMMAND [\fIARGUMENT\fP\]
.SH DESCRIPTION
.PP
blog is a tool that lets you manage an ephemeral blog via https, and keep a
non-ephemeral archive in gemini and gopher. By default, the blog will only
keep 3 posts, but you can adjust this by setting the
.B BLOG_OUTPUT_DIRECTORY
environment variable.
.SH COMMANDS
.TP
.B "help   "
Display help.
.TP
.B version
Display version information.
.TP
.B "status "
Display status of your blog.
.TP
\fBadd\fR \fIFILE\fR
Adds a new blog post at position 0
.TP
\fBupdate\fR \fIFILE\fR
Update the blog post at position 0
.TP
.B generate
Generates the static assets for the blog and archive
.TP
\fBpublish\fR \fIREMOTE_HOST\fR
Copies the files for the ephemeral blog to REMOTE_HOST. (eg. username@host:/path/to/remote)
.TP
\fBpublish-archive\fR \fIREMOTE_HOST\fR
Copies the files for the permanent archive to REMOTE_HOST. (eg. username@host:/path/to/remote)
.TP
\fBadd-remote\fR \fIGIT_URL\fR
Adds or updates a git remote to sync the blog contents
.TP
.B remove-remote
Removes the git remote associated with the blog
.TP
.B sync-up
Pushes to the git remote. This will force a push.
.TP
.B sync-down
Gets the files from the blog. This will erase any local changes.
.SH ENVIRONMENT VARIABLES
You can configure some aspects of the blog using environment variables
.TP
.B BLOG_MAX_POSTS
Sets the maximum number of posts. Defaults to 3.
.TP
.B BLOG_CONFIG_DIRECTORY
Sets the location for configuration. Defaults to \fI$XDG_CONFIG_HOME/blog\fR.
.TP
.B BLOG_DATA_DIRECTORY
Sets the location for the main blog data: posts, archive, templates, and static
files. Defaults to \fI$XDG_DATA_HOME/blog\fR.
.TP
.B BLOG_OUTPUT_DIRECTORY
Sets the location for the generated static files ready to be published.
Defaults to \fI$XDG_CACHE_HOME/blog\fR.
.SH TEMPLATES
You can override the default templates by creating a \fItemplates\fR directory
inside your blog data root (\fBXDG_DATA_HOME/blog\fR).

For the ephemeral blog you can create \fIfeed.xml\fR, \fIindex.html\fR, and
\fIindex.txt\fR inside of \fItemplates\fR. These files are then parsed with
the following values.

.TP
.I posts
A collection of posts
.TP
.I has_posts
Whether the posts array has any posts or not (boolean)
.TP
.I posts_length
The number of posts in the posts array

.P
Each post in the posts collection has the following fields.

.TP
.I id
The id of the post
.TP
.I created_on
The numerical timestamp when the blog post was added
.TP
.I created_on_utc
The RFC-2822 String of post creation date
.TP
.I title
The title of the post
.TP
.I raw
The raw gemini text of the template
.TP
.I html
The parsed html generated from the gemini
.TP
.I escaped_html
Same as html, but escaped for inclusion in XML

.P
To customize your gemini and gopher archives you can provide an \fIindex.gmi\fR
and \fIindex.gph\fR files that will be used as templates for the archive.
However the data structure is different.

.TP
.I posts
A collection of archive posts
.TP
.I archive_length
The number of archive posts in the posts array

.P
Each post in the archive has the following fields

.TP
.I id
The id of the post
.TP
.I slug
The slug of the post (used to generate URLs)
.TP
.I title
The title of the post
.SH TEMPLATE SYNTAX
The template is a subset of DoT. You can print values, iterate over collections,
or check conditionals. The template does not allow expressions. You can only
reference keys in the structure above.

You can print values

\f(CW
{{= posts.raw }}
\fR

You can iterate over collections. With the format COLLECTION: MEMBER, where
MEMBER will become part of the template below, and the template will be
repeated for each member of COLLECTION.
.nf
\f(CW
{{~ posts: post }}
{{= post.html}}
{{~}}
\fR
.fi
Finally, you can do conditionals. To negate a conditional you can prepend !.
.nf
\f(CW
{{# !has_posts }}
<p> There are no posts </p>
{{#}}
\fR
.fi
.SH STATIC FILES
Any files inside the \fIstatic\fR directory of your blog data root
(\fBXDG_DATA_HOME/blog\fR) will be copied as is. This is useful for any images,
javascript files or stylesheets that you use in your posts or templates.
.SH VERSION
.BR 7.0.0
.SH HOMEPAGE
.I https://r.bdr.sh/blog.html
.SH AUTHORS
\ Rubén Beltrán del Río <\fIblog@r.bdr.sh\fP>