198 lines
6.1 KiB
Groff
198 lines
6.1 KiB
Groff
.Dd $Mdocdate$
|
|
.Dt SBS 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sbs
|
|
.Nd A simple blogging system
|
|
.Sh SYNOPSIS
|
|
.Nm sbs
|
|
.Op Fl v
|
|
.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. It compiles a collection of
|
|
Markdown files into HTML using
|
|
.Xr lowdown 1
|
|
with some additional processing and capabilities.
|
|
.Pp
|
|
Arguments are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Fl v
|
|
Increase verbosity.
|
|
Specify once for command feedback and twice to see each file being built by the
|
|
.Cm build
|
|
subcommand.
|
|
.El
|
|
.Pp
|
|
Commands are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Cm build Ar
|
|
Build the given markdown file(s), sandwiching the content of each file between
|
|
the template header and footer and placing the resulting file(s) in the
|
|
\&./static/ directory. If run without arguments, build everything under the
|
|
\&./content/ directory. Files without a .md extension will be copied verbatim to
|
|
\&./static/.
|
|
.It Cm genfeed
|
|
Compile an Atom feed containing the configured number of posts found under the
|
|
configured blog directory, outputting the file to
|
|
.Pa 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.
|
|
.It Cm push
|
|
Executes the "pushCommand" command specified in the configuration file. Intended to
|
|
be used to deploy the contents of the
|
|
.Pa static/
|
|
directory.
|
|
.It Cm version
|
|
Prints the version number of
|
|
.Nm
|
|
..
|
|
.El
|
|
.Sh SITE CONFIGURATION
|
|
A site created by
|
|
.Nm
|
|
must have a
|
|
.Pa 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. example.com). This must be the same as the
|
|
directory of the website (i.e. what you specified when using the 'sbs new site'
|
|
command).
|
|
.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. The
|
|
defaults are sensible and usually do not have to be changed.
|
|
.It pushCommand
|
|
An arbitrary shell command executed by
|
|
.Nm
|
|
when using the
|
|
.Cm push
|
|
command. Intended to be used for publishing your site
|
|
(e.g. openrsync -rv static/* user@website:/var/www/html).
|
|
.It numFeedEntries
|
|
The number of entries (posts) to include in the atom feed generated by the
|
|
.Cm genfeed
|
|
command.
|
|
.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
|
|
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
|
|
Or, simply run:
|
|
.Pp
|
|
.Dl sbs build
|
|
.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
|
|
.Pa 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
|
|
.Pa 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 generated with a small amount of CSS
|
|
that makes the site look presentable. A link tag pointing to this file is in
|
|
.Pa templates/header.html .
|
|
.It Pa templates/
|
|
The directory that contains the following template files:
|
|
.It Pa templates/header.html
|
|
HTML that will be placed before the content of a compiled markdown file.
|
|
.It Pa templates/footer.html
|
|
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 1
|
|
.Xr lowdown 5
|
|
.Sh AUTHORS
|
|
.Nm
|
|
was created by
|
|
.An Jake Bauer ,
|
|
.Mt jbauer@paritybit.ca .
|