git.r.bdr.sh - rbdr/blog/blob - 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>