commit 874cae4594e4650a60a3b47deb2dd2da8c74d6fb
parent ba3ac156caf43f94e01e9a664e4a22009fb36fd3
Author: Jake Bauer <jbauer@paritybit.ca>
Date: Wed, 8 Mar 2023 18:10:51 -0500
Improve manual
Fix references to gemtext functionality that was removed, link to
lowdown(1), improve wording, etc.
Diffstat:
| M | sbs.1 | | | 53 | ++++++++++++++++++++++++++++++----------------------- |
1 file changed, 30 insertions(+), 23 deletions(-)
diff --git a/sbs.1 b/sbs.1
@@ -10,20 +10,22 @@
.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 supports compiling both
-gemtext and markdown into HTML, but primarily works with Markdown documents.
+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
Commands are as follows:
.Bl -tag -width Ds
.It Cm build Ar
-Build the given markdown or gemtext file(s), sandwiching the content of each
-given file between the template header and footer files and placing the
-resulting files in the ./static/ directory. If run without arguments, build
-everything under the ./content/ directory.
+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.
.It Cm genfeed
Compile an Atom feed from all posts found under the configured blog directory,
-outputting the file to ./static/feed.xml. Note that posts under the blog
-directory must be in markdown format only.
+outputting the file to
+.Pa static/feed.xml .
.It Cm new Ar subcommand
.Bl -tag -width Ds
.It page Ar file
@@ -45,10 +47,12 @@ overwriting of an existing site.
Note that if a subdirectory is specified for any given path, that subdirectory
must already exist.
.Nm
-will not create subdirectories for you.
+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 static/ directory.
+be used to deploy the contents of the
+.Pa static/
+directory.
.It Cm version
Prints the version number of
.Nm
@@ -57,7 +61,9 @@ Prints the version number of
.Sh SITE CONFIGURATION
A site created by
.Nm
-must have a config.ini file containing options that
+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
@@ -68,7 +74,7 @@ options are as follows:
.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). This must be the same as the
+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
@@ -77,15 +83,13 @@ The directory under which all blog posts will be.
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.
+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 "push" command. Intended to be used for publishing your site
-(e.g. rsync -rv static/* user@website:/var/www/html, ssh user@website "cd
-/var/www/html; git pull", etc.)
+(e.g. openrsync -rv static/* user@website:/var/www/html).
.El
.Sh EXIT STATUS
.Nm
@@ -122,9 +126,10 @@ 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.
+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 :
@@ -137,7 +142,8 @@ 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.
+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
@@ -148,9 +154,9 @@ 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.
+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.
+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
@@ -164,6 +170,7 @@ a file created using
.Cm new Ar subcommand
commands.)
.Sh SEE ALSO
+.Xr lowdown 1
.Xr lowdown 5
.Sh AUTHORS
.Nm
