From: Ruben Beltran del Rio Date: Tue, 12 Mar 2024 21:47:56 +0000 (+0100) Subject: Add manual file X-Git-Tag: 7.0.0~10 X-Git-Url: https://git.r.bdr.sh/rbdr/blog/commitdiff_plain/2e0000a6ebc1f58df6f3c1bf93ecb964a83ea938 Add manual file --- diff --git a/man/blog.1 b/man/blog.1 new file mode 100644 index 0000000..30a03c4 --- /dev/null +++ b/man/blog.1 @@ -0,0 +1,172 @@ +.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 }} +

There are no posts

+{{#}} +\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>