152 lines
5.0 KiB
Groff
152 lines
5.0 KiB
Groff
.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 .
|