sbs

A Simple Blogging System.
git clone https://git.sr.ht/~jbauer/sbs
Log | Files | Refs | README | LICENSE

sbs.1 (5901B)


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