(This file was last written for SBWG version 0.8.8. SBWG and its README are works in progress. The list of features and other details may have been changed by now.)

SBWG (steeph's bash website generator) is a bash script that generates a static HTML website from raw text files.

SBWG is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar.
See http://www.wtfpl.net/txt/copying/ for more details.

# Features

* Generates static HTML structure from a source file structure
* Simple image galleries
* Weblog/Blog generation
    * Categorised posts with multiple levels
    * Blog entries can be additionally categorised as topics for an index view
    * Classical blog view, filterable by category, topic, author, language or author AND one of the others
    * Support for multi-author weblogs
    * Attached image galleries
* Stylesheet templates
* Modifications/Additions to the generation process on a per-web-site basis with hooks and a sourced settings file
* Easy staging
* Simple RSS feed


## Feature ideas and requested features

I will work on these when I'm satisfied with the state of the current feature set and have some time.

* Audio attachements/postcast support, audio player
* Video attachement support
* Video support in galleries
* Support for more image file formats
* Easy image embedding, entry images
* Directory structure in the source directories (directory trees for entries and pages)
* ATOM feeds and multiple RSS feeds for single tags, categories or topics
* Interactive setup script


# Installation

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

There is currectly no setup script. Installation is straight forward though if you understand how SBWG works. **There are more instructions in the INSTALL file** if
not. **Those install instructions are sufficient to get started.** The README file (yes, this one here) contains complete descriptions of SBWGs functionality. So,
if you just want to quickly set up a web site using the example web site as a starting point, head over the the INSTALL file now. If you want to know more than you
need to know, read on.

After installation of SBWG and during setting up/editing of a web site you might find useful tips in the HOWTO file.


## Requirements:

* bash 4 (This script is not tested with other shells.)
* imagemagick (or compatible `convert`; only needed for image gallery generation)
* This file does not go into installing a web server. SBWG only generates web sites. It does not make them accessible over a network. Please refer to instructions on
  how to install a web server for your operating system.
* The style sheets included in the example website make use of CSS 3. This is not an issue. I just thought I better mention it.
* The same goes for the generated HTML, which assumes HTML 5 support.


## Setting up the script

* Extract the package to a location outside of your web root
* Move the files to a directory in PATH or add the SBWG directory path to your PATH.
* Check if the file 'sbwg' (and optionally the file 'genentry') is executable, make it executable if it is not already.


## Setting up a new web site

The steps necessary to create a new web site depend very much on what you wish your web site to be. SBWG is sort of flexible. You can change variables and add your
own code on a per-website basis in the 'settings' file of a web site. But you don't have to get into the details of what SBWG can do and how it works, exactly.
If you have never created a web site with SBWG before, I recommend to copy the 'example' directory and make changes to the copied example according to your
requirements/wishes.


### Setting up a new web site from the example template

The 'example' directory included in this package contains the complete source for a web site with a couple of pages, blog, a gallery and some other files. All of
the following steps are technically optional. Omitting one will simply mean that whatever you didn't set/change will stay as it was set for the example web site.
 
* Copy the 'example' directory to a suitable location, e.g. ~/my_website
* Edit the 'settings' file to change your website's title, url/domain name, style template choice, default output directory, etc.
* If you have not changed the default output directory, create a symlink called 'html' to point to your web root.
* Edit the 'footer' file to include any HTML code that you want to be included at the bottom of every generated HTML page.
* Edit or replace the logo.svg file with you web site's logo.
* Place any other miscellaneous files needed by your web site in the 'files' directory.
* Create or edit CSS files in the 'styles' directory according to your wishes. Which files are used is determined by the 'style=' setting in the settings file.
* Create and/or edit files in the 'pages' directory for "static" web pages not related to a weblog.
* Create blog entries in the 'entries' directory. You can use the 'genentry' script, write files from scratch or use a template file that you have filled with
    header lines that you regularly use.
* Add galleries in the 'galleries' directory, one directory per gallery. Simplyt place JPEG and PNG files in these directories.
* Run 'sbwg --complete' or 'sbwg -c' to create the HTML website in the default output directory with its default settings. Use the '-o'/'--output' option to
    specify a different output directory, e.g. for testing/a non-public preview.


### Setting up a new web site from scratch

If you've copied the example directory, you're fine and you don't need all these details described below. You may skip reading any or all of them.

Setting up a new web site source directory from scratch is something that is not currently explained well and complete in any of the help files. I suggest you
just copy the example or parts from it or look at how the example does things. Below I'll explain what a SBWG web site source directory consists of and what
settings and features exist, though. That should help if you really want to do it from scratch. It isn't complicated. It's just a matter of knowing what's what.


# (files and directories of) a web site source directory

The following files and directories can be used to build a web site with SBWG. All except the `settings` file are optional. That means if there are no pages, no
galleries and no entries the scriipt will just prepare for generating an empty web site and may (depending on the contents of the settings file) actually produce
output in the output directory. Files and directories that are not listed below will simply be ignored by the script.


## settings

The `settings` file must exist in order for SBWG to recognise the directory as a SBWG web site source directory. SBWG will refuse to generate the website if this
file isn't there and it will assume that there is a valid SBWG web site source structure in the same directory if the file exists.

You can use the file to inject any Bash code that should be executed before the web site is generated. Commonly it is only used to set a few global variables and
declare hooks (see the "Hooks" section below). You can copy the settings file from the example directory or peek at it for explanations of the settings that should
be set for any new web site. I suggest that you include at least the 'sitename' and 'url' settings. There are more settings worth knowing about. Have a look at the
settings file in the example directory or see the short descriptions of all settings further down in this file under "Settings".


## files

The `files` directory can be used to store random and miscellaneous files that you would like to be publicly available. These can be JavaScript files used by the
web site, image files that you use somewhere in the site's content, files that you want to link to to be downloaded, or anything else really.

The directory just get copied to the output directory when generating the web site. This means that, unless prevented by web server settings, anything in this
directory will become publicly available on the resulting web site.


## header

The 'header' file does not exist in this version of SBWG. If it exists, it is ignored. The head section of the generated HTML pages can be influenced by using a
hook. (see the "Hooks" section below)


## footer

The contents of this file gets appended to every generated HTML file. The file has to end with:

  </body>
</html>

Before that you can put anything that should appear at the end of every HTML page. For example a `<footer>` tag with a copyright notice.

This file will likely be replaced by a hook in the future. But in this version it is still used and has to close the `<body>` and `<html>` tags. Without this file
(and the closing tags for body and html) the generated HTML will not be valid. (Although it would probably work in the most used browsers.)


## styles

The styles directory can contain several style sheet sets that are independent of each other. When generating a web site only one of these sets is used. By default
the style "style" is used unless a different style is specified either in the web site's settings file (see "Settings" section below) or through the command line
option `--style` (`-s`). That means that by defult all CSS files with a name starting with "style-"... and ending in .css as well as the file "style.css" will be
linked in the header of every generated HTML file. For example the following files will all be used if they exist:
style.css
style-colours.css
style-mobile.css
style-anything-that-you-want.css

If you want to make custom changes to the default style cheet, you can either edit the existing style.css or add a file named style-custom.css or similar.

If you want to create your own style set, you can specify its name in your web site's setting file or pass it with the --style option upon generation.

Example file names: If your style is set as "my_style" then the files
my_style.css
my_style-sidebar.css
my_style-awesomeness.css
my_style-something.css

and so on, will be linked in the header of every generated HTML file headers.

If you would like to link a CSS file on some but not all HTML file's headers or insert internal CSS into the header, you can use the hook `hook_head`. (See the
"Hooks" section below.)


## pages

This directory contains the web site's page source files.

A page in SBWG terminology is a file consisting of a title and content, that will be turned into an HTML file but not linked to from other generated files
automatically. Typical uses for pages are the index page, a contact page, about page or any other HTML page that has to contain the header, sidebar, menu and footer
but is not part of the weblog.

It is recommended to at least have a file named `index` in this directory. It will be turned into an HTML page and placed as "index.html" in the root of the output
directory so that it will be the default index page if not specified otherwise by webserver settings. Respectively, all other text files that are directly in the
`pages` directory are turned into HTML files and placed directly in the output directory. It is currently not possible to have pages generated into subdorectories.
This is on the todo list though.

A page does not have to contain a source file header as is recommended for entries (see the "entries" section below). But if a page source file starts with a line
that starts with `title:`, that title will be used as the heading. For example if the first line of a file in the `pages` directory is

`title:This Is The Tilte But It Has A Typo`

then the generated HTML page will turn that line into an `<h2>` heading.


## entries

This directory contains the source files for the entries that make up the web site's weblog. If there will be no weblog on the site, the dorectory should be empty.
But please note that SBWG was made for creating a web site with a weblog and generating a site without any entries may currentmpdirtly still create empty heading and
useless links in the generated HTML.

Subdirectories inside the `entries` directory are currently not supported. This is a feature on the todo list though.

An entry source file is basically just a text file with the contents of the blog entry in HTML. A simple text file with one or multiple lines is a valid entry source
file. But ususally an entry source file consists of a source file header and its content. The heade can consist of one or many tags of different types, specifying
e.g. the entry's title, author, creation date and the categories and topics it's filed in. Please see the sections "Blog Entries" and "Tags" below for a description
of how the source file header and tags work. The important tag types are used in the blog entries that are contained in the example web site. Looking at the header
of those entries is probably enough to get started.


## tagicons

In this dorectory you can place icons that should be displayed in place of tags in entries' headers. The file name has to be `tagtype:tagname.png`.

Examples:

If you place a file called `lang:en.png` in this directory, the image is inserted in the header of every entry that's tagged with `lang:en`. The text `lang:en` is
will not be diplayed in those header, only the image.

If you place a file called `author:foobär.png` in this directory, the author foobär has an avatar that will be displayed in place of their name in the header of
posts tagged with `author:foobär`.

Make sure to resize all images placed in this folder to be of small, sensible dimensions.

If you would like to add icons in addition to the tag name in text, it is suggested to use CSS. Every tag displayed in entry headers has its name as a class
selector.


## html

By default this is the output directory of no other output directory was specified either in the web site's setting file or through the command line option
`--output` (`-o`). It is recommended to replace this directory with a symbolic link to your webserver's webroot. But this depends entirely on your preferences. By
default the generated website is placed in this directory. If it is not accessible by the webserver at the same time then you'll habe to copy it over manually in
order to publish the web site.

If a different directory is used as the output directory (see the sections "Settings" and "Generating a web site" below) then this directory is not needed.


# Settings

A setting in a web sites `settings` file is just a global variable that's set for the script before generating the web site. Therefore a setting can be set by
writing the setting name followed by a `=` followed by the value in an otherwise empty line. The can be no blank before or after the `=`. Values with special
characters (that includes spaces) have to be encloded in `"`s.

Examples:

`sitename="ExSite (The Example Web Site)"`
The Name of the web site needs to have a `"` before and one after. Otherwise, an error will occur.

`thumbsize=200`
The value `200` does not contain any special characters. Therefore no `"` is needed. It doesn't matter whether the value is enclosed in them or not.

All settings are optional. If a setting is not set in the settings file, a default value is used. The following variables/settings are meant to be set in the
settings file. Additional settings can be declared in the same way if they don't have the same way as an existing global variable. Those additional variables can
then be used in hooks. (See the "Hooks" section below.)

`sitename` - The name/title of the website as displayed in the header and used in the browser window title bar/browser tabs.

`url` - The url is used when external documents that link to the web site are generated, e.g. the RSS feed.

`webbase` - A prefix that is prepended to every link that is generated. Unless the web site will be sitting in a subdirectory, this should always be "/".  

`style` - The name of the style set that should be used if none is specified by command line option. See the "Styles" section below to learn which files this will include.

`odir` - The path of the output directory.
 
`thumbsize` - The maximum width and height of gallery image thumbnails when attached to blog entries.

`thumbsizemini` - The maximum width and height of gallery image thumbnails on gallery pages.

`previewsize` - The maximum width and height of gallery image previews as displayed on gallery pages. This should be large enough to view the image in full but doesn't need to be too large as the original image file will be linked for the case that somebody wants to download the full resolution.

`perpage` - The maximum number of entries that will be included in one HTML page when generating agpages. When there are more entries that belong on the tagpage, it is devided into several HTML pages and a pager is added at the bottom.

`tagiconsize` - This setting is currently ignored. You may do the same with this line.

`duals` - This setting is currently ignored. You may do the same with this line.

`details` - This setting is currently ignored. You may do the same with this line.

`exclude` - This setting is currently ignored. You may do the same with this line.


## Hooks

A hook is a function that is declared in the settings file of a web site. It does not exist in the SBWG script and therefore is not executed if it is not included
in the settings file. No hook is required. There are many hooks that get executed at different points in the generation of a web site. Therefore they can be used to
inject code at certain points of the script for only the web site who's settings file contains the hook. This way the script does not need to be edited for
customisation and different web sites can be customised differently.

Inside a hook all variables that exist at the point at which the hook is executed can be read and changed. Output can be added to the file that is being generated at
that point, additional commands can be executed, and so on. This makes the settings file a very flexible tool for the customisation of a web site and SBWG itself,
and a possible source of errors when not used carefully.

When writing an elaborate new hook (as opposed to copying an example hook or hook from an existing settings file) you will probably not be able to avoid reading at
least some of the SBWG script to see how your goal can be accomplished. There are a couple of helper functions in the script that of course can also be used in
hooks. I will not explain here every part of the code that could possibly be of relevance when writing a new hook. I don't know what you want to do with your hook,
so I wouldn't know what to limit myself to.

The below table lists all hooks that SBWG currently has and the local variables that are accesibble inside these hooks. Additionally there are a couple of global
variables that are accessible from inside every hook:

* `shellbase` - The path of the input directory - The directory of the web site that is being generated
* `tmpdir` - The path of the temporary directory - This directory will be deleted after the script is done or when it fails.
* `version` - The version of SBWG that is processing the website
* `entrylist` - An array that contains all entry names that exist on the web site
* `entrylists` - An associative array with all existing tag names as keys and lists of entry names as values
* `tagslist` - An array that contains all existing tags
* `gallerylist` - An array that contains the names of all galleries on this web site than contain any supported image files
* All variables that are declared in the settings file as well as the default values for settings that are not set in the settings file

   ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
   ┃ Function Name                   │ Called At                                     │ Availbale Variables                   │ Usage Examples                      ┃
   ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┠─────────────────────────────────┼───────────────────────────────────────────────┼───────────────────────────────────────┼─────────────────────────────────────┨
   ┃ hook_        │                       │                     │             ┃
   ┃              │                       │                     │             ┃
   ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛


# Styles

ääääääääääääääää


# Pages

äääääää


# Blog Entries

ääääääääääääääääääää


## Tags

äääääääääää


### Tag Types

öööööö


## Tagpages

ööööööööööööööööö


## Tagicons

ööööööööööööö


# Entry Images

This is a requested feature that will be addded in an upcoming version of SBWG. It will allow for featured images and single images that can be attached to an entry
without writing the `<img>` tag yourself or abusing the gallery feature.


# Galleries

äääääääääää


# Generating a web site (command line options)

ääääääääääääääää


## Example Commands

ööööööööö



# Other remarks

SBWG is work in progress and I don't always publish new versions immedietely. Feel free to contact me via e-mail at steeph@steeph.de for any requests, bug reports,
criticism, suggestions, wishes, complaints or declarations of love.

There is a HOWTO file that included in this package where you can read more about how you can use SBWG and how you can accomplish specific things that have not been
mentioned in this README file.

There is no version control in use for SBWG. Feel free to put it on Github or whatever. Maybe I'll start to use it, too, some day.

SBWG is free. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar.
See http://www.wtfpl.net/txt/copying/ for more details.
