A Simple Blogging System.
git clone
Log | Files | Refs | README | LICENSE

sbs.1 (5989B)

      1 .Dd $Mdocdate$
      2 .Dt SBS 1
      3 .Os
      4 .Sh NAME
      5 .Nm sbs
      6 .Nd A simple blogging system
      7 .Sh SYNOPSIS
      8 .Nm sbs
      9 .Op Fl v
     10 .Cm command
     12 .Nm
     13 is a static site builder designed to fill a gap between writing HTML by hand and
     14 more complicated generators such as Hugo or Jekyll. It compiles a collection of
     15 Markdown files into HTML using
     16 .Xr lowdown 1
     17 with some additional processing and capabilities.
     18 .Pp
     19 Arguments are as follows:
     20 .Bl -tag -width Ds
     21 .It Fl v
     22 Increase verbosity.
     23 Specify once for command feedback and twice to see each file being built by the
     24 .Cm build
     25 subcommand.
     26 .El
     27 .Pp
     28 Commands are as follows:
     29 .Bl -tag -width Ds
     30 .It Cm build Ar
     31 Build the given markdown file(s), sandwiching the content of each file between
     32 the template header and footer and placing the resulting file(s) in the
     33 ./static/ directory. If run without arguments, build everything under the
     34 ./content/ directory.
     35 .It Cm genfeed
     36 Compile an Atom feed from all posts found under the configured blog directory,
     37 outputting the file to
     38 .Pa static/feed.xml .
     39 .It Cm new Ar subcommand
     40 .Bl -tag -width Ds
     41 .It page Ar file
     42 Create a new markdown document populated with a basic page structure.
     43 .It post Ar file
     44 Create a new markdown document populated with a basic page structure for a
     45 blog post.
     46 .It site Ar directory
     47 Create a new directory structure with basic template and configuration files
     48 under
     49 .Ar directory Ns No .
     50 These sample files should be edited to conform to the webmaster's needs.
     51 .Pp
     52 .Nm
     53 will refuse to work on a directory that already exists to prevent accidental
     54 overwriting of an existing site.
     55 .Pp
     56 .El
     57 Note that if a subdirectory is specified for any given path, that subdirectory
     58 must already exist.
     59 .Nm
     60 will not create subdirectories.
     61 .It Cm push
     62 Executes the "pushCommand" command specified in the configuration file. Intended to
     63 be used to deploy the contents of the
     64 .Pa static/
     65 directory.
     66 .It Cm version
     67 Prints the version number of
     68 .Nm
     69 ..
     70 .El
     72 A site created by
     73 .Nm
     74 must have a
     75 .Pa config.ini
     76 file containing options that
     77 .Nm
     78 will use when building pages and generating the Atom feed. All of the below
     79 options are populated with default values when the config file is created by
     80 .Nm
     81 and all options must be defined in a site's config.ini file. Configuration
     82 options are as follows:
     83 .Bl -tag -width Ds
     84 .It siteURL
     85 The URL of the website's root page (e.g.
     86 .It siteName
     87 The name of the website (e.g. This must be the same as the
     88 directory of the website (i.e. what you specified when using the 'sbs new site'
     89 command).
     90 .It blogDir
     91 The directory under which all blog posts will be.
     92 .It languageCode
     93 The language code for the language the content is written in (e.g. en-ca, de,
     94 nl).
     95 .It buildOptions
     96 The arguments passed to lowdown which tell it how to compile given pages. The
     97 defaults are sensible and usually do not have to be changed.
     98 .It pushCommand
     99 An arbitrary shell command executed by
    100 .Nm
    101 when using the "push" command. Intended to be used for publishing your site
    102 (e.g. openrsync -rv static/* user@website:/var/www/html).
    103 .El
    104 .Sh EXIT STATUS
    105 .Nm
    106 exits 0 on success, and >0 if an error occurs.
    107 .Sh EXAMPLES
    108 To create a new site called "":
    109 .Pp
    110 .Dl sbs new site
    111 .Pp
    112 The examples below assume the webmaster is currently inside of the newly created
    113 "" directory and has edited the files and configuration generated by
    114 sbs to their liking.
    115 .Pp
    116 To create an index page for this site:
    117 .Pp
    118 .Dl sbs new page content/
    119 .Pp
    120 To create a new blog post, assuming the webmaster has configured "blog/"
    121 as the directory for their blog posts:
    122 .Pp
    123 .Dl sbs new post content/blog/
    124 .Pp
    125 After populating the above files with content, to build the two previously
    126 created files:
    127 .Pp
    128 .Dl sbs build content/ content/blog/
    129 .Pp
    130 Or, simply run:
    131 .Pp
    132 .Dl sbs build
    133 .Pp
    134 To generate an Atom feed containing all posts under the configured blog
    135 directory (which will just be a single post in this example):
    136 .Pp
    137 .Dl sbs genfeed
    138 .Pp
    139 After following all these steps, the webmaster will have several files in the
    140 .Pa static/
    141 directory including the generated Atom feed and HTML files. All of these files
    142 are ready to be uploaded to a webserver.
    143 .Sh FILES
    144 The following files are created inside of a site directory created by
    145 .Nm :
    146 .Bl -tag -width Ds
    147 .It Pa config.ini
    148 The file containing all configuration for the site. It is populated with sample
    149 values for each option that can be configured.
    150 .It Pa content/
    151 The directory where markdown documents are expected to be. Under this directory,
    152 a subdirectory containing blog posts can be created for use with
    153 .Nm
    154 .Cm genfeed
    155 and configured in
    156 .Pa config.ini .
    157 .It Pa static/
    158 The directory containing all static assets (images, videos, robots.txt, etc.),
    159 including the HTML files built by
    160 .Nm .
    161 .It Pa static/style.css
    162 The main CSS file for the website. It is generated with a small amount of CSS
    163 that makes the site look presentable. A link tag pointing to this file is in
    164 .Pa templates/header.html .
    165 .It Pa templates/
    166 The directory that contains the following template files:
    167 .It Pa templates/header.html
    168 HTML that will be placed before the content of a compiled markdown file.
    169 .It Pa templates/footer.html
    170 HTML that will be placed after the content of a compiled markdown file.
    171 .El
    173 lowdown: <tag>: unknown keyword - This error message is encountered when lowdown
    174 tried to parse the metadata tag <tag> but that tag was not found in the given
    175 file. This is usually caused either by accidentally omitting a required tag, or
    176 leaving the content for a tag blank. Make sure that there is at least some text
    177 for each MultiMarkdown metadata tag in the file you are trying to build, and
    178 that all the required tags exist. (Required tags are automatically written to
    179 a file created using
    180 .Nm
    181 .Cm new Ar subcommand
    182 commands.)
    183 .Sh SEE ALSO
    184 .Xr lowdown 1
    185 .Xr lowdown 5
    186 .Sh AUTHORS
    187 .Nm
    188 was created by
    189 .An Jake Bauer ,
    190 .Mt .