Readme.md updates

More updates to Readme.md

diff --git a/Readme.md b/Readme.md
index 02ed5ca..3ec7e8e 100644 (file)
--- a/Readme.md
+++ b/Readme.md
@@ -3,8 +3,8 @@
 ## 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)
@@ -63,4 +63,106 @@ source directory of BiaWeb2 wherein you had cloned the repository
     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
+
+Once you have successfully compiled BiaWeb2, you will want to create your website.
+
+
+
+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
+
+The _templates_ folder 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 required 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