title:How To Install SBWG And Create A Web Site For SBWG
<p>These roughly 10 steps should get you started setting up a new web site; from the example site to a personalised generated HTML web site. If you want to set up a
web site completely from scratch yourself, please read the README file to learn all the details of how SBWG works and what else it can do. It contains explanations
for every option, setting, the file structure, what tags exist and how they work, how style sets and galleries can be added and so on.</p>

<p>The guide in this file is for shorter install instructions that are enough to set up a new web site. You can still refer to the README file later when you want to
learn how to add or change things that are not explained here.</p>

<h1>0. Download SBWG</h1>

<p>You can get the latest published version from https://log.steeph.de/SBWG.html</p>

<h1>1. Requirements:</h1>

<ul>
<li>bash 4.4 (None of the scripts have been tested with other shells.)</li>
<li>Coreutils</li>
<li>imagemagick (or compatible <code>mogrify</code>; only needed for image gallery generation)</li>
<li>perl (optional for better filtering of broken tag values)</li>
<li>A working web server (if you want to actually publish the generated website)</li>
</ul>

<h1>2. Optional and not recommended anymore: Edit the script itself.</h1>

<p>If you want to change aspects of the website generation itself, feel free to go to town in any or all of the script's functions. I encourage you to document your
changes and/or submit them to be integrated in a future version of the script. Please e-mail your suggestions, whishes or submissions to a-sbwg@steeph.de</p>

<p>This step should not be necessary for most web sites with current verisons of SBWG because its workings can be influenced on a per-web-site basis through a settings
file and hooks.</p>

<h1>3. Make sure the script(s) is/are executable.</h1>

<p>The main script file of SBWG is called <code>sbwg</code>. This is all that is needed to generate a website. There are little helper scripts, too, that you can optionally make
executable if you want to use them. One of them is <code>sbwg-genentry</code>, that can help to generate a new blog entry.</p>

<p>Example: <code>chmod +x sbwg</code></p>

<p>Either move/copy the script(s) to a directory included in $PATH or add this directory to $PATH.</p>

<p><code>cp sbwg ~/bin/</code></p>

<p>Alternatively you may want to set aliases for the script instead. For example add to ~/.bashrc:</p>

<p><code>alias sbwg="~/bin/sbwg/sbwg"</code>
<code>alias genentry="~/bin/sbwg/sbwg"</code></p>

<p>Wherever you end up putting SBWG, place the script somewhere not accessible by the web server. It is a good idea to keep SBWG in a place where nobody can access it
who isn't supposed to, obviously. The Bash script file <code>sbwg</code> can be used without any of the other files from the SBWG package. You can place it in your <code>bin</code>
directory or wherever you would like to execute it from.</p>

<h1>4. Create a source directory for your web site.</h1>

<p>A web sites source directory is where the settings, stylesheets and other files are stored and where you edit and add content (web pages and blog entries). You can
manage multiple unrelated web sites with SBWG by simply having different source directories for different web sites.</p>

<p>If you just want to generate the example web site for now, you can copy the <code>example</code> directory to a nice place where your web site source files should live.</p>

<p><code>cp -r sbwg/example ~/mywebsite</code></p>

<p>The web site's source directory may not be accessible by other users! Code injection through the files in this directory is a feature by design. I suggest that you
do not make the files in this directory viewable publicly, either.</p>

<p>You can skip to the next step now. If you rather create a source directory for a new web site from scratch instead of copying the example web site, see the README
file for more information.</p>

<h1>5. Set up output directory.</h1>

<p>If the script is called without the option <code>-o</code> or <code>--output</code> then the web site is generated into the directory specified in the <code>settings</code> file. If the setting
<code>odir=</code> is not set in the settings file either then the <code>html</code> directory inside the source directory is used. Commonly <code>html</code> is a softlink to your web root (see
below). If no symlink or directory exists in this place, a directory is created.</p>

<p>Option 1: Manually copy or move the contents of the <code>html</code> directory to a location accessible by your webserver after every time the website has been re-generated.
This way the generated website won't immedietely be publicly available. You can check that everything looks right before you copy the newly generated website to its
actual destination.</p>

<p>Option 2: Create a symlink (replace the paths in the example according to your web server and configuration):</p>

<p>Example: <code>cd /path/to/your/website/source/; ln -s /var/www/html html</code></p>

<p>This way the website source directory is sitting outside the www directory but the generated website will automatically be written to the publicly accessible
location. The website will be incomplete during generation and any mistakes you made will be immedietly published, as well. </p>

<p>Option 3: Use the output directory option when generating the website.</p>

<p>Example: <code>sbwg -c -i ~/blog_source -o /var/www/html</code></p>

<p>You can create an alias to always include the output directory option by default.</p>

<p>Examples:</p>

<p><code>alias sbwg='sbwg -o /var/www/html'</code>
<code>alias updatemysite='sbwg -i ~/mysite -o /var/www/html'</code></p>

<p>Option 4: Edit the $odir variable in the web site's settings file to a path inside your web root. This will change the default output directory that is used when no
output directory is specified with the <code>-o</code> or <code>--output</code> option. You can still use the <code>-o</code> or <code>--output</code> option to overwrite this setting when you want to
generate the web site to a different output directory than usually, e.g. to view the generated site before bublishing it.</p>

<h1>6. Optional: Set default options in the web site's settings file.</h1>

<p>If you want to, go over the variables that are being set in he <code>settings</code> file and edit them according to your wishes.</p>

<p><code>sitename="My Glorious Web Site"
  The name/title of the web site as displayed at the top of every page and used in the browser window title bar/browser tabs.</code></p>

<p><code>url="https://example.de/"
  The URL that is used in the RSS feeds that are generated alongside the HTML of this web site. Without it, links in the generated RSS feeds will not work.</code></p>

<p><code>style=my_style</code>
  The style set that should be used by default for this web site. Create a <code>my_style.css</code> or <code>my_style-somethingsomtheing.css</code> file or leave the setting as it is
  and edit the existing CSS files. (see below)</p>

<h1>7. Optional: Customise CSS files/stylesheets</h1>

<p>A SBWG style can consist of onne or multiple files who's names end in <code>.css</code> and start with the style name that's either set in the settings file (see above) or
passed as an argument to the <code>--style</code> or <code>-s</code> option upon web site generation.</p>

<p>Examples for the style name <code>my_style</code>:</p>

<ul>
<li><p>my_style.css</p></li>
<li><p>my_style-layout.css</p></li>
<li><p>my_style-galleries.css</p></li>
<li><p>my_style-whatever.css</p></li>
</ul>

<p>If the set style name is <code>my_style</code>, all of these files will be linked in the HTML header of generated files.</p>

<p>The default style set of the example web site is <code>stinpell</code>. It consists of only one file: <code>stinpess.css</code>. If you want to edit it, go ahead and do so, or preserve it
my copying it to create your own style. (Then you'll have to change the style name in the settings file or pass the style name of your own style when generating the
web site.) You can add style sheets to this file or add another file according to the anming convention <code>STYLENAME-something.css</code> (the style name followed by a dash
followed by some string followed by <code>.css</code>).</p>

<h1>8. Fill your web site with content.</h1>

<p>If you just want to generate the example web as it is, you can skip to the next step for now. This can be helpful to compare the generated HTML site with the source
to learn how tags and setting influece the result, for example. But ultimately you'll probably want to add your own content that the web site is for.</p>

<p>For this short guide I'll confine the descriptions to three short ones: pages, blog entries and galleries. You can learn more about what you can do with tags and
images in the detailed descriptions for the respective features in the README file.</p>

<h2>Pages</h2>

<p>There are two files in the <code>pages</code> directory in the example web site's source directory: index and about. When generating the site, these files will be turned into
HTML files named index.html and about.html that will be placed in the root directory of the web site so that they will be accessible at
https://your-domain.net/index.html and https://your-domain.net/about.html</p>

<p>They will contain all the HTML header, the sidebar and the footer according to the setting of this web site. But these are just independent pages for which no link
will automatically be placed in the menu. (This is a feature that will be added in the future, though.) The example web site links to them in the menu by use of
the hook <code>hook_navbar</code> in the settings file. Currently this is the best way to add links or anything else to the navbar.</p>

<p>Page files can contain HTML or just text. Their bodies will be written to their generated HTML files unfiltered and unparsed.</p>

<p>Page files can reside directly in the pages/ directory or in subdirectories. The directory structure inside of the pages/ directory from the input directory will be
recreated in the root of the output directory.</p>

<h2>Entries</h2>

<p>The <code>entries</code> directory in the example web site's source directory contains the blog entries of the web site. Each text file will be turned into an HTML file of the
same name with .html attached to it. An entry file can optionally contain a header consisting of one or several tags. Below the header is the body that can be just
text or contain HTML tags. The header contains meta-data like categories, topics, created date, name of the author, etc. and will be removed by SBWG when generating
 the HTML files. The body will be used unfiltered.</p>

<p>Some of the most important tag types are:</p>

<ul>
<li><p><code>title:</code> - The title of the blog entry.</p></li>
<li><p><code>created:</code> - A numeric value or string starting with a number that indicates when this entry was first created. It's used for sorting on tagpages if no overwriting tag exists in the header.</p></li>
<li><p><code>edited:</code> - A numeric value or string starting with a number that indicates when this entry was last edited. It overwrites <code>created:</code> in the sorting on tagpages.</p></li>
<li><p><code>sort:</code> - A string that overwrites <code>created:</code> and <code>edited:</code> in the sorting on tagpages.</p></li>
<li><p><code>author:</code> - The name of the author of this blog entry.</p></li>
<li><p><code>lang:</code> - A string used to indicate a langugage the entry is written in. Multiple <code>lang:</code> tags can be used in an entry header.</p></li>
<li><p><code>cat:</code> - A category this entry will be tagged with. Multiple <code>cat:</code> tags can be used in an entry header.</p></li>
<li><p><code>top:</code> - A topic this entry is adressing. Multiple <code>top:</code> tags can be used in an entry header. Topics can have multiple layers. To file an entry in a subtopic, simply add a <code>:</code> and the name of the child topic at the end of the topic line.</p></li>
</ul>

<p><code>created:</code>, <code>edited:</code> and <code>sort:</code> can contain alphanumeric values. No specific date format is specified. Values starting with anything else than a number turn the
entry into a stickied one, meaning it will be displayed at the top of every category tagpage that that entry is tagged for.</p>

<p>Have a look at the headers of the entry files in the <code>example/entries/</code> directory for example usages. Detailed explanations for all tag types can be found in the
README file.</p>

<p>Entry files can reside directly in the entries/ directory or in subdirectories. The directory structure inside of the entries/ directory from the input directory
will not be recreated in the output directory, meaning that no two entries can have the same name and all entries will be generated directly into the entries/
directory in the output directory.</p>

<h2>Galleries</h2>

<p>The <code>galleries</code> directory in the example web site's source directory can contain image galleries, one per directory, that each can be independent of any other
content on the web site or linked to a blog entry.</p>

<p>Simply put a drectory with the name of the gallery into the <code>galleries</code> directory and some image files in that new directory to create a new gallery. Currently only
JPEG and PNG files are supported. Upon generation of the web site, a gallery page and several resized copies of the images (for previews and thumbnails) are created
and the gallery will be linked in the sidebar. If an entry file of the same name as the gallery directory exists in the <code>entries</code> directory, that entry will be
linked at the top of the gallery page, the gallery page will be linked at the bottom of that entry and thumbnails of the gallery images will be attached to the
entry.</p>

<h1>9. Generate the website.</h1>

<p>The SBWG script can (re-)generate the entire website at once or only parts of it. When generating the a wesite for the first time, it makes sense to generate the
entire website first. THe following command executed from the web site's directory will do this using the default settings that are defined in the <code>settings</code> file.</p>

<p><code>sbwg -c</code></p>

<p>To generate the web site from or to a different directory than <code>$PWD</code>, you can use the <code>--output</code> (<code>-o</code>) and <code>--input</code> (<code>-i</code>) options.</p>

<p><code>sbwg -c -i "/path/to/web/site/source/directory" -o "/path/to/directory/where/the/generated/html/will/be/stored"</code></p>

<p>Those are stupid example paths. But it should make clear how to use them. Another example to be sure (using the long style options this time):</p>

<p>`sbwg --input "~/my web site" --output /srv --complete</p>

<p>This generates the web site that is sitting in <code>"my web site"</code> inside the user's home directory completely and puts the generated file structure in <code>/srv/</code>. The order
of options does not matter. Short and long style options can be mixed.</p>

<p>In future runs you may want to re-generate only parts of the web site (only galleries, only the blog or even just a single page) to update only the things that have
been changed. The <code>--help</code> (or <code>-h</code>) option gives an overview of all available options. There are more detailed descriptions in the README file.</p>
