From: Ruben Beltran del Rio <redacted>
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?ds=sidebyside

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 }}
+<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>