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 11 .Sh DESCRIPTION 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 71 .Sh SITE CONFIGURATION 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. https://www.example.com/) 86 .It siteName 87 The name of the website (e.g. example.com). 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 "example.com": 109 .Pp 110 .Dl sbs new site example.com 111 .Pp 112 The examples below assume the webmaster is currently inside of the newly created 113 "example.com" 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/index.md 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/hello-world.md 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/index.md content/blog/hello-world.md 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 172 .Sh DIAGNOSTICS 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 jbauer@paritybit.ca .