X-Git-Url: https://harishankar.org/repos/?p=biaweb2.git;a=blobdiff_plain;f=Readme.md;h=c28876bfe32365bea1717953916c01a8124eb7f5;hp=3ec7e8ea7f25e4d9e50d739fcda90ee952ba5f46;hb=HEAD;hpb=ac1d4ac9259e624faae74dabf8feea18b1029fa8 diff --git a/Readme.md b/Readme.md index 3ec7e8e..c28876b 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,199 @@ 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 + +### Recommendations for Uploading Content and Static Resources + +Often, a website is more than just the HTML pages. You have images, for instance needed by +your pages. While BiaWeb2 does not handle static content, it's quite easy to deal with static +content, since they need to be uploaded to a fixed location on your website. The `gensite.sh` +script can be adapted to copy/sync your remote website with the generated output of BiaWeb2 +as well as static resources by adding a couple of extra lines: + +Assume that we keep our static resources (like images) in _images_ within the folder +_/path/to/mywebsite/images_. We can set the script to automatically sync the images +folder with your remote website (assumed to be accessible at `host@remote`). + + + !/bin/sh + rm -rf Out/ + /path/to/biaweb2/biaweb2 -i Home -t templates -o Out + + # Sync contents of the Out folder with the remote site at host@remote + rsync -avrz --delete ~/path/to/mywebsite/Out/ host@remote:/path/to/www/ + + # Sync static resources such as images to remote website + rsync -avrz --delete /path/to/mywebsite/images/ host@remote:/path/to/www/images + +The resources can then be linked from your individual pages with markdown like this + + ... + # Heading + + This is some content + ![My image](images/testimage.jpg) + +Since BiaWeb2 uses the `` tag to define the base URL, the above code will work +from any location on your website. + +## Further Customization and Notes + +* You can edit the contents of the _templates_ folder to get a more unique look and feel. + Templates are just plain HTML bits with no logic (other than the template vars marked + within curly braces). The __style.css.tpl__ file is the CSS bit that is embedded in + all pages of the site. At present there is no way to get a different look and feel for + different categories or parts of the site. + +* The file __stringbits.txt__ contain general strings that are used to describe parts of + your website. This can also be customized, but each line stands for a particular item + and should not be interchanged. Ensure that changes to a particular line describe the + same item (in a different way). For example the text `List of Articles` may be substituted + by `List of Docs` or `Documents` but changing it to `Categories` will not make sense. + +* The generated website from the default template should conform to HTML 5. If there are + any errors in the resultant HTML, please raise an + [issue](https://gitlab.com/harishankarv/biaweb2/-/issues/new) to + address it and it will be fixed. In general, please raise an issue for any bugs, + feedback or feature requests. However, as far as features are concerned, there is no + plan to make this a comprehensive website management tool. The key philosophy of this + tool is simplicity and I plan to keep it that way. + +* __Limitation of RSS Feed:__ At present the RSS feed generated by the script in + __feed.xml__ does not fetch any articles from sub-categories and only fetches articles from' + its own category. This may be addressed in the future, depending on whether this is seen + as necessary. \ No newline at end of file