## Overview
BiaWeb2 is a static site generator written in C++, that takes a directory tree
-of documents (in Markdown format - more on that later) and outputs a website
-with the same tree structure, based on a set of templates.
+of documents (in Markdown format - more on that later) and outputs a complete website
+with the same tree structure and proper navigation, based on a set of templates.
BiaWeb2 supports infinite nesting level of source sub-directories, with
each directory representing a "category". Thus, a website can have (say)
scons
If successful, you should get an executable file `biaweb2` in the same directory
-If not, check whether you have installed all the requirements.
\ No newline at end of file
+If not, check whether you have installed all the requirements.
+
+## Usage
+
+### Getting started - creating the sources
+
+Once you have successfully compiled BiaWeb2, you will want to create your website
+sources.
+
+This is probably the longest step, since you need to create the directory structure
+of your website (you probably want to plan this properly, though you can of course
+easily change the structure by rearranging or moving the folders as needed). You also
+need to create the content of your website.
+
+A typical workflow is described below:
+
+1. First create a base directory for your entire website project (including sources,
+ templates, static resources like images etc.) Replace `~/path/to/mywebsite` with
+ your own path.
+
+ ````
+ mkdir ~/path/to/mywebsite
+ cd ~/path/to/mywebsite
+ ````
+
+2. Copy the default template from the BiaWeb2 source directory to your website path
+
+ ````
+ cp -r /path/to/biaweb2/templates ~/path/to/mywebsite/
+ ````
+3. Create a source directory that will hold your website contents. Name this directory
+ as "Home" or similar (this name will be used as the base name of your website)
+
+ ````
+ mkdir ~/path/to/mywebsite/Home
+ ````
+
+4. Now you can add all the categories within this folder. Let's say you want a section
+ for blogs. Create a directory called _Blog_ within the _Home_ folder
+
+ ````
+ mkdir ~/path/to/mywesbite/Home/Blog
+ ````
+
+5. Under each category you can create the regular content as text files, with the following
+ simple format (title, description, keywords, creation date/time followed by
+ the markdown text. Each of title, description, keywords and creation date/time lives
+ in its own line):
+
+ ````
+ Title of the article
+ some description of the article
+ keywords,keyword 1,keyword2
+ 2020-05-20 18:00 UTC
+ markdown contents of the document
+ ...
+ ````
+ Here, the first line is the title, followed by description on the second line, keywords on
+ the third line and date/time of creation of the article (in YYYY-MM-DD HH:II Z format). If
+ the format of date/time differs, BiaWeb2 will issue a warning when generating the website
+ and you will have a wrong date/time stamp on the article in the generated page. All four
+ (title, description, keywords and creation date/time are mandatory).
+
+6. Using the above format, add as many documents as you want within the created categories.
+ There is no special file extension required as BiaWeb2 will read all the files in the
+ source directories. However, you can conventionally use the `.md` extension to allow your
+ favourite text editor to recognize the file as markdown and provide syntax highlighting
+ and/or completion etc. You can keep adding more categories and articles as you wish.
+ Note that, symbolic links will not get followed by BiaWeb2 and hence keep all the files
+ as regular text files.
+
+7. You can optionally have a special named `index.md` or `index` file in every folder (case
+ sensitive though the file extension does not matter) to describe the index page
+ generated by BiaWeb2. The content of this file is pure Markdown and will be
+ shown as a summary on the __index.html__ page generated by BiaWeb2 under each folder
+ (category). Apart from the content of the `index` file, the generated __index.html__ file
+ will also automatically create links to the articles under the category and the links
+ to the sub-categories. For example, under the _Home_ folder we can create and index.md
+ file with the following content:
+
+ ````
+ # Hello and Welcome to my website
+
+ Hello and welcome to my website. Here you can find my writings on various topics.
+ Please explore the various categories more information
+ ````
+
+ The above will be used as a "summary" to describe the category.
+
+### Setting up the templates
+
+If you copied the _templates_ folder correctly from the BiaWeb2 sources, the _templates_ folder
+within your `~/path/to/mywebsite/~ will have the following files:
+
+* doclistitem.tpl.html
+* doclist.tpl.html
+* genericlinklistitem.tpl.html
+* genericlistitem.tpl.html
+* __main.tpl.html__
+* navigationbit.tpl.html
+* __rssitem.tpl.xml__
+* __rss.tpl.xml__
+* sidebar.tpl.html
+* stringbits.txt
+* style.tpl.css
+
+The minimum necessary files to be edited to get your website working are __main.tpl.html__,
+__rssitem.tpl.xml__ and __rss.tpl.xml__ as those files need your website URL in
+the right places to work properly. The __style.tpl.css__ file is also of interest if you
+want to modify the default look and feel of your site.
+
+__main.tpl.html__ is the base template and the file looks like this by default (only the key
+parts are highlighted for clarity):
+
+ <!DOCTYPE html>
+ ...
+ <!-- change as appropriate - just don't touch anything within the curly braces!! -->
+ <title>My Site - {title}</title>
+ ...
+ <meta name="keywords" content="site key words {keywords}">
+ <meta name="description" content="Site Description - {description}">
+ <!-- change base href to your site URL -->
+ <base href="http://my.site">
+ ...
+ <body>
+ <!-- change My Site to your own header -->
+ <header><h1>My Site</h1></header>
+ ...
+ ...
+
+ <footer>
+ <!-- change copyright to your own copyright -->
+ My copyright
+ </footer>
+ </body>
+ </html>
+
+As suggested don't touch anything within the curly braces in this file or any other
+template file in this folder as they represent the template variables. Change the
+site URL and title, keywords, description, header and copyright as per your requirements
+and save. Again, __DO NOT__ delete or edit anything within `{` and `}`.
+
+Note that, BiaWeb2 relies on the `<base>` HTML tag to be present to generate the proper
+links structure. There are, of course, pros and cons to using this tag, but at present,
+this tag is required to generate a site with BiaWeb2.
+
+__rss.tpl.xml__ and __rssitem.tpl.xml__ are required to generate the RSS feed for
+each category (note that RSS feeds are generated only for documents/articles within that
+category alone and not any sub-categories. This is a limitation at present).
+
+Again, change the title, description and URL as required:
+
+__rss.tpl.xml__
+
+ <?xml version="1.0" encoding="UTF-8" ?>
+ <rss version="2.0">
+ <channel>
+ <!-- change title description and link as needed-->
+ <!-- don't touch anything within the curly braces -->
+ <title>My Site - {title}</title>
+ <description>Site Description</description>
+ <link>http://my.site</link>
+ <pubDate>{pubdate:%a, %d %b %Y %H:%M:%S %z}</pubDate>
+ {items}
+ </channel>
+ </rss>
+
+__rssitem.tpl.xml__
+
+ <item>
+ ...
+ <!-- change http://my.site to your actual site URL -->
+ <!-- don't touch anything within the curly braces-->
+ <link>http://my.site/{url}</link>
+ <guid>http://my.site/{url}</guid>
+ <pubDate>{pubdate:%a, %d %b %Y %H:%M:%S %z}</pubDate>
+ </item>
+
+Change the URL part `http://my.site/` to your site's url (dont't remove the
+`{url}` bit from the above)
+
+That's it. Now your templates are set up to generate your website with proper links.
+
+Though this process looks tedious, it is basically a one-time setup. Once your template is
+configured, you almost never need to touch it again (unless you are changing the URL of
+your website)
+
+### Generating the output
+
+Now we can invoke `biaweb2` on your website source. To make invoking `biaweb2` convenient
+make a small shell script called `gensite.sh` within `~/path/to/mywebsite` with the
+following contents:
+
+ !/bin/sh
+ /path/to/biaweb2/biaweb2 -i Home -t templates -o Out
+
+and change it to executable (from the command line):
+
+ chmod +x ~/path/to/mywebsite/gensite.sh
+
+Invoke the `gensite.sh` script from within the `~/path/to/mywebsite` directory:
+
+ ./gensite.sh
+
+You should get output similar to this
+
+ Document tree:
+ 0 Home
+ 1 +--Blog
+ Output in: Out
+ Generated in (s): 0.0848904
+
+Assuming you have only one folder _Blog_ inside the _Home_ folder.
+
+__Note__ that if you provide a trailing `/` to your input folder parameter `-i`
+then the "base" node of your tree will not have any name - it will simply be
+blank. Your output would look like this:
+
+ Document tree:
+ 0
+ 1 +--Blog
+ Output in: Out
+ Generated in (s): 0.0848904
+
+Use this "feature" as you wish.
+
+That's it. You can now transfer the contents of the _Out_ folder to your web host
+through FTP or SFTP.
+
+### Updating your website
+
+Simply make any changes to the source folder (by creating content files and folders) and
+invoke the above shell script. BiaWeb2 will regenerate the entire tree, as it does not maintain
+the state of any incremental updates. If you are making major changes, it is recommended that
+you delete the output directory before re-generating, as this will be a "clean" build. Change
+your `gensite.sh` script as below to ensure that the output directory is clean with no stale
+content (i.e. removed files / folders from the source tree):
+
+ !/bin/sh
+ rm -rf Out/
+ /path/to/biaweb2/biaweb2 -i Home -t templates -o Out
\ No newline at end of file