From: Harishankar Date: Tue, 26 May 2020 09:45:36 +0000 (+0530) Subject: Readme.md updates X-Git-Url: https://harishankar.org/repos/?a=commitdiff_plain;h=ac1d4ac9259e624faae74dabf8feea18b1029fa8;p=biaweb2.git Readme.md updates More updates to Readme.md --- diff --git a/Readme.md b/Readme.md index 02ed5ca..3ec7e8e 100644 --- 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