commit 3aa52dbb0e3fc3328f3df25d786d48e4c8ea138c
parent c05a650fe21dc8a22d054980c6fb96b136947e7f
Author: Jake Bauer <jbauer@paritybit.ca>
Date: Thu, 23 Jun 2022 06:01:55 -0400
Create manpage
Diffstat:
| A | sbs.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 .
