Readme.md

   1 # Readme
   2
   3 ## Overview
   4
   5 BiaWeb2 is a static site generator written in C++, that takes a directory tree
   6 of documents (in Markdown format - more on that later) and outputs a complete website
   7 with the same tree structure and proper navigation, based on a set of templates.
   8
   9 BiaWeb2 supports infinite nesting level of source sub-directories, with
  10 each directory representing a "category". Thus, a website can have (say)
  11 a structure like
  12
  13     + Home
  14     + ----- Blog
  15     + ------+------ Travel
  16     + ------+------ History
  17     + ------+------ Personal
  18     + ------+------ Technology
  19     + ----- Creative
  20     + ------+------ Reviews
  21     + ------+------ +------- Books
  22     + ------+-------+--------+-------- Fiction
  23     + ------+-------+--------+-------- Non-fiction
  24     + ----- Miscellaneous
  25
  26 Thus the entire structure of the website is represented by the filesystem
  27 hierarchy of directories (which I think is an intuitive way of organizing
  28 categories).
  29
  30 `biaweb2` is a command-line program that performs the entire website
  31 generation in one step. The usage is:
  32
  33     biaweb2 -i <inputdir> -o <outputdir> -t <templatedir> [-q]
  34
  35 Where `<inputdir>` is the input directory, `<outputdir>` is the destination
  36 directory and `<templatedir>` is the location of the template files. The
  37 `templates` directory in the __biaweb2__ source package provides a default
  38 template that can be further customized to suit your needs. The main philosophy
  39 of BiaWeb2 is to be as configuration-free as possible and hence most of the
  40 customization for a specific website is within the templates themselves. The
  41 option `-q` is quiet-mode, to suppress the messages.
  42
  43 ## Getting and compiling BiaWeb2
  44
  45 BiaWeb2 works on *nix-like operating systems.
  46
  47 To get BiaWeb2, clone the git repository (from the command line)
  48
  49     git clone https://gitlab.com/harishankarv/biaweb2.git
  50
  51 To compile you require the following dependencies and a C++ compiler. Check your
  52 distribution package manager for more information
  53
  54 * libmarkdown2-dev or equivalent package
  55    ([discount](https://www.pell.portland.or.us/~orc/Code/discount/))
  56 * libfmt-dev or equivalent package ([fmt](https://github.com/fmtlib/fmt))
  57 * scons ([scons](https://scons.org/))
  58
  59 Once you have got the dependencies, compile using scons from inside the
  60 source directory of BiaWeb2 wherein you had cloned the repository
  61
  62     cd biaweb2/
  63     scons
  64
  65 If successful, you should get an executable file `biaweb2` in the same directory
  66 If not, check whether you have installed all the requirements.
  67
  68 ## Usage
  69
  70 ### Getting started
  71
  72 Once you have successfully compiled BiaWeb2, you will want to create your website.
  73
  74
  75
  76 1. First create a base directory for your entire website project (including sources,
  77    templates, static resources like images etc.) Replace `~/path/to/mywebsite` with
  78    your own path.
  79
  80       ````
  81       mkdir ~/path/to/mywebsite
  82       cd ~/path/to/mywebsite
  83       ````
  84
  85 2. Copy the default template from the BiaWeb2 source directory to your website path
  86
  87       ````
  88       cp -r /path/to/biaweb2/templates ~/path/to/mywebsite/
  89       ````
  90 3. Create a source directory that will hold your website contents. Name this directory
  91    as "Home" or similar (this name will be used as the base name of your website)
  92
  93       ````
  94       mkdir ~/path/to/mywebsite/Home
  95       ````
  96
  97 4. Now you can add all the categories within this folder. Let's say you want a section
  98    for blogs. Create a directory called _Blog_ within the _Home_ folder
  99
 100       ````
 101       mkdir ~/path/to/mywesbite/Home/Blog
 102       ````
 103
 104 5.  Under each category you can create the regular content as text files, with the following
 105     simple format  (title, description, keywords, creation date/time followed by
 106     the markdown text. Each of title, description, keywords and creation date/time lives
 107     in its own line):
 108
 109       ````
 110       Title of the article
 111       some description of the article
 112       keywords,keyword 1,keyword2
 113       2020-05-20 18:00 UTC
 114       markdown contents of the document
 115       ...
 116       ````
 117     Here, the first line is the title, followed by description on the second line, keywords on
 118     the third line and date/time of creation of the article (in YYYY-MM-DD HH:II Z format). If
 119     the format of date/time differs, BiaWeb2 will issue a warning when generating the website
 120     and you will have a wrong date/time stamp on the article in the generated page. All four
 121     (title, description, keywords and creation date/time are mandatory).
 122
 123 6.  Using the above format, add as many documents as you want within the created categories.
 124     There is no special file extension required as BiaWeb2 will read all the files in the
 125     source directories. However, you can conventionally use the `.md` extension to allow your
 126     favourite text editor to recognize the file as markdown and provide syntax highlighting
 127     and/or completion etc. You can keep adding more categories and articles as you wish.
 128     Note that, symbolic links will not get followed by BiaWeb2 and hence keep all the files
 129     as regular text files.
 130
 131 7. You can optionally have a special named `index.md` or `index` file in every folder (case
 132    sensitive though the file extension does not matter) to describe the index page
 133    generated by BiaWeb2.  The content of this file is pure Markdown and will be
 134    shown as a summary on the __index.html__ page generated by BiaWeb2 under each folder
 135    (category). Apart from the content of the `index` file, the generated __index.html__ file
 136    will also automatically create links to the articles under the category and the links
 137    to the  sub-categories. For example, under the _Home_ folder we can create and index.md
 138    file with the following content:
 139
 140       ````
 141       # Hello and Welcome to my website
 142
 143       Hello and welcome to my website. Here you can find my writings on various topics.
 144       Please explore the various categories more information
 145       ````
 146
 147     The above will be used as a "summary" to describe the category.
 148
 149 ### Setting up the templates
 150
 151 The _templates_ folder have the following files:
 152
 153 * doclistitem.tpl.html
 154 * doclist.tpl.html
 155 * genericlinklistitem.tpl.html
 156 * genericlistitem.tpl.html
 157 * __main.tpl.html__
 158 * navigationbit.tpl.html
 159 * __rssitem.tpl.xml__
 160 * __rss.tpl.xml__
 161 * sidebar.tpl.html
 162 * stringbits.txt
 163 * style.tpl.css
 164
 165 The minimum required files to be edited to get your website working are __main.tpl.html__,
 166 __rssitem.tpl.xml__ and __rss.tpl.xml__ as those files need your website URL in
 167 the right places to work properly. The __style.tpl.css__ file is also of interest if you
 168 want to modify the default look and feel of your site.