sbs

A Simple Blogging System.
git clone https://git.sr.ht/~jbauer/sbs
Log | Files | Refs | README | LICENSE

commit 3aa52dbb0e3fc3328f3df25d786d48e4c8ea138c
parent c05a650fe21dc8a22d054980c6fb96b136947e7f
Author: Jake Bauer <jbauer@paritybit.ca>
Date:   Thu, 23 Jun 2022 06:01:55 -0400

Create manpage

Diffstat:
Asbs.1 | 151++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 151 insertions(+), 0 deletions(-)

diff --git a/sbs.1 b/sbs.1 @@ -0,0 +1,151 @@ +.Dd $Mdocdate$ +.Dt SBS 1 +.Os +.Sh NAME +.Nm sbs +.Nd A simple blogging system +.Sh SYNOPSIS +.Nm sbs +.Cm command +.Sh DESCRIPTION +.Nm +is a static site builder designed to fill a gap between writing HTML by hand and +more complicated generators such as Hugo or Jekyll. +.Pp +Commands are as follows: +.Bl -tag -width Ds +.It Cm build Ar +Build the given markdown file(s), sandwiching the content of each given markdown +file between the template header and footer files and placing the resulting +files in the ./static/ directory. +.It Cm genfeed +Compile an Atom feed from all posts found under the configured blog directory, +outputting the file to ./static/feed.xml. +.It Cm new Ar subcommand +.Bl -tag -width Ds +.It page Ar file +Create a new markdown document populated with a basic page structure. +.It post Ar file +Create a new markdown document populated with a basic page structure for a +blog post. +.It site Ar directory +Create a new directory structure with basic template and configuration files +under +.Ar directory Ns No . +These sample files should be edited to conform to the webmaster's needs. +.Pp +.Nm +will refuse to work on a directory that already exists to prevent accidental +overwriting of an existing site. +.Pp +.El +Note that if a subdirectory is specified for any given path, that subdirectory +must already exist. +.Nm +will not create subdirectories for you. +.El +.Sh SITE CONFIGURATION +A site created by +.Nm +must have a config.ini file containing options that +.Nm +will use when building pages and generating the Atom feed. All of the below +options are populated with default values when the config file is created by +.Nm +and all options must be defined in a site's config.ini file. Configuration +options are as follows: +.Bl -tag -width Ds +.It siteURL +The URL of the website's root page (e.g. https://www.example.com/) +.It siteName +The name of the website (e.g. John Smith's Blog). +.It blogDir +The directory under which all blog posts will be. +.It languageCode +The language code for the language the content is written in (e.g. en-ca, de, +nl). +.It buildOptions +The arguments passed to lowdown which tell it how to compile given pages. This +option is set to a sensible default and should not be changed under normal +circumstances. +.El +.Sh EXIT STATUS +.Nm +exits 0 on success, and >0 if an error occurs. +.Sh EXAMPLES +To create a new site called "example.com": +.Pp +.Dl sbs new site example.com +.Pp +All of the following commands must be run from within a given site's directory. +The examples below assume the webmaster is currently inside of the newly created +"example.com" directory and has edited the files and configuration generated by +sbs to their liking. +.Pp +To create an index page for this site: +.Pp +.Dl sbs new page content/index.md +.Pp +To create a new blog post, assuming the webmaster has configured "blog/" +as the directory for their blog posts: +.Pp +.Dl sbs new post content/blog/hello-world.md +.Pp +After populating the above files with content, to build the two previously +created files: +.Pp +.Dl sbs build content/index.md content/blog/hello-world.md +.Pp +To generate an Atom feed containing all posts under the configured blog +directory (which will just be a single post in this example): +.Pp +.Dl sbs genfeed +.Pp +After following all these steps, the webmaster will have several files in +the ./static/ directory including the generated Atom feed and HTML files. All of +these files are ready to be uploaded to a webserver. +.Sh FILES +The following files are created inside of a site directory created by +.Nm : +.Bl -tag -width Ds +.It Pa config.ini +The file containing all configuration for the site. It is populated with sample +values for each option that can be configured. +.It Pa content/ +The directory where markdown documents are expected to be. Under this directory, +a subdirectory containing blog posts can be created for use with +.Nm +.Cm genfeed +and configured in config.ini. +.It Pa static/ +The directory containing all static assets (images, videos, robots.txt, etc.), +including the HTML files built by +.Nm . +.It Pa static/style.css +The main CSS file for the website. It is an empty file by default. A stylesheet +link tag pointing to this is already in the templates/header.html file. +.It Pa templates/ +The directory that contains the following template files: +.It Pa templates/header.html +The HTML that will be placed before the content of a compiled markdown file. +.It Pa templates/footer.html +The HTML that will be placed after the content of a compiled markdown file. +.El +.Sh DIAGNOSTICS +lowdown: <tag>: unknown keyword - This error message is encountered when lowdown +tried to parse the metadata tag <tag> but that tag was not found in the given +file. This is usually caused either by accidentally omitting a required tag, or +leaving the content for a tag blank. Make sure that there is at least some text +for each MultiMarkdown metadata tag in the file you are trying to build, and +that all the required tags exist. (Required tags are automatically written to +a file created using +.Nm +.Cm new Ar subcommand +commands.) +.Sh SEE ALSO +.Xr lowdown 5 +.Sh AUTHORS +.Nm +was created by +.An Jake Bauer , +.Mt jbauer@paritybit.ca .