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.
9 BiaWeb2 supports infinite nesting level of source sub-directories, with
10 each directory representing a "category". Thus, a website can have (say)
15 + ------+------ Travel
16 + ------+------ History
17 + ------+------ Personal
18 + ------+------ Technology
20 + ------+------ Reviews
21 + ------+------ +------- Books
22 + ------+-------+--------+-------- Fiction
23 + ------+-------+--------+-------- Non-fiction
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
30 `biaweb2` is a command-line program that performs the entire website
31 generation in one step. The usage is:
33 biaweb2 -i <inputdir> -o <outputdir> -t <templatedir> [-q]
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.
43 ## Getting and compiling BiaWeb2
45 BiaWeb2 works on *nix-like operating systems.
47 To get BiaWeb2, clone the git repository (from the command line)
49 git clone https://gitlab.com/harishankarv/biaweb2.git
51 To compile you require the following dependencies and a C++ compiler. Check your
52 distribution package manager for more information
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/))
59 Once you have got the dependencies, compile using scons from inside the
60 source directory of BiaWeb2 wherein you had cloned the repository
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.
72 Once you have successfully compiled BiaWeb2, you will want to create your website.
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
81 mkdir ~/path/to/mywebsite
82 cd ~/path/to/mywebsite
85 2. Copy the default template from the BiaWeb2 source directory to your website path
88 cp -r /path/to/biaweb2/templates ~/path/to/mywebsite/
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)
94 mkdir ~/path/to/mywebsite/Home
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
101 mkdir ~/path/to/mywesbite/Home/Blog
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
111 some description of the article
112 keywords,keyword 1,keyword2
114 markdown contents of the document
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).
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.
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:
141 # Hello and Welcome to my website
143 Hello and welcome to my website. Here you can find my writings on various topics.
144 Please explore the various categories more information
147 The above will be used as a "summary" to describe the category.
149 ### Setting up the templates
151 The _templates_ folder have the following files:
153 * doclistitem.tpl.html
155 * genericlinklistitem.tpl.html
156 * genericlistitem.tpl.html
158 * navigationbit.tpl.html
159 * __rssitem.tpl.xml__
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.