From: Harishankar Date: Tue, 26 May 2020 11:12:07 +0000 (+0530) Subject: Readme.md updates X-Git-Url: https://harishankar.org/repos/?a=commitdiff_plain;h=ca54cd9a481727176c82a43e7ca452cdbbdbc408;p=biaweb2.git Readme.md updates Completed Readme.md with the main usage. To add: tips, tricks and suggestions for static content etc. --- diff --git a/Readme.md b/Readme.md index 3ec7e8e..679cdf2 100644 --- a/Readme.md +++ b/Readme.md @@ -67,11 +67,17 @@ If not, check whether you have installed all the requirements. ## Usage -### Getting started +### Getting started - creating the sources -Once you have successfully compiled BiaWeb2, you will want to create your website. +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 @@ -148,7 +154,8 @@ Once you have successfully compiled BiaWeb2, you will want to create your websit ### Setting up the templates -The _templates_ folder have the following files: +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 @@ -162,7 +169,138 @@ The _templates_ folder have the following files: * stringbits.txt * style.tpl.css -The minimum required files to be edited to get your website working are __main.tpl.html__, +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. \ No newline at end of file +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): + + + ... + + My Site - {title} + ... + + + + + ... + + +

My Site

+ ... + ... + + + + + +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 `` 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__ + + + + + + + My Site - {title} + Site Description + http://my.site + {pubdate:%a, %d %b %Y %H:%M:%S %z} + {items} + + + +__rssitem.tpl.xml__ + + + ... + + + http://my.site/{url} + http://my.site/{url} + {pubdate:%a, %d %b %Y %H:%M:%S %z} + + +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