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.
70 ### Getting started - creating the sources
72 Once you have successfully compiled BiaWeb2, you will want to create your website
75 This is probably the longest step, since you need to create the directory structure
76 of your website (you probably want to plan this properly, though you can of course
77 easily change the structure by rearranging or moving the folders as needed). You also
78 need to create the content of your website.
80 A typical workflow is described below:
82 1. First create a base directory for your entire website project (including sources,
83 templates, static resources like images etc.) Replace `~/path/to/mywebsite` with
87 mkdir ~/path/to/mywebsite
88 cd ~/path/to/mywebsite
91 2. Copy the default template from the BiaWeb2 source directory to your website path
94 cp -r /path/to/biaweb2/templates ~/path/to/mywebsite/
96 3. Create a source directory that will hold your website contents. Name this directory
97 as "Home" or similar (this name will be used as the base name of your website)
100 mkdir ~/path/to/mywebsite/Home
103 4. Now you can add all the categories within this folder. Let's say you want a section
104 for blogs. Create a directory called _Blog_ within the _Home_ folder
107 mkdir ~/path/to/mywesbite/Home/Blog
110 5. Under each category you can create the regular content as text files, with the following
111 simple format (title, description, keywords, creation date/time followed by
112 the markdown text. Each of title, description, keywords and creation date/time lives
117 some description of the article
118 keywords,keyword 1,keyword2
120 markdown contents of the document
123 Here, the first line is the title, followed by description on the second line, keywords on
124 the third line and date/time of creation of the article (in YYYY-MM-DD HH:II Z format). If
125 the format of date/time differs, BiaWeb2 will issue a warning when generating the website
126 and you will have a wrong date/time stamp on the article in the generated page. All four
127 (title, description, keywords and creation date/time are mandatory).
129 6. Using the above format, add as many documents as you want within the created categories.
130 There is no special file extension required as BiaWeb2 will read all the files in the
131 source directories. However, you can conventionally use the `.md` extension to allow your
132 favourite text editor to recognize the file as markdown and provide syntax highlighting
133 and/or completion etc. You can keep adding more categories and articles as you wish.
134 Note that, symbolic links will not get followed by BiaWeb2 and hence keep all the files
135 as regular text files.
137 7. You can optionally have a special named `index.md` or `index` file in every folder (case
138 sensitive though the file extension does not matter) to describe the index page
139 generated by BiaWeb2. The content of this file is pure Markdown and will be
140 shown as a summary on the __index.html__ page generated by BiaWeb2 under each folder
141 (category). Apart from the content of the `index` file, the generated __index.html__ file
142 will also automatically create links to the articles under the category and the links
143 to the sub-categories. For example, under the _Home_ folder we can create and index.md
144 file with the following content:
147 # Hello and Welcome to my website
149 Hello and welcome to my website. Here you can find my writings on various topics.
150 Please explore the various categories more information
153 The above will be used as a "summary" to describe the category.
155 ### Setting up the templates
157 If you copied the _templates_ folder correctly from the BiaWeb2 sources, the _templates_ folder
158 within your `~/path/to/mywebsite/~ will have the following files:
160 * doclistitem.tpl.html
162 * genericlinklistitem.tpl.html
163 * genericlistitem.tpl.html
165 * navigationbit.tpl.html
166 * __rssitem.tpl.xml__
172 The minimum necessary files to be edited to get your website working are __main.tpl.html__,
173 __rssitem.tpl.xml__ and __rss.tpl.xml__ as those files need your website URL in
174 the right places to work properly. The __style.tpl.css__ file is also of interest if you
175 want to modify the default look and feel of your site.
177 __main.tpl.html__ is the base template and the file looks like this by default (only the key
178 parts are highlighted for clarity):
182 <!-- change as appropriate - just don't touch anything within the curly braces!! -->
183 <title>My Site - {title}</title>
185 <meta name="keywords" content="site key words {keywords}">
186 <meta name="description" content="Site Description - {description}">
187 <!-- change base href to your site URL -->
188 <base href="http://my.site">
191 <!-- change My Site to your own header -->
192 <header><h1>My Site</h1></header>
197 <!-- change copyright to your own copyright -->
203 As suggested don't touch anything within the curly braces in this file or any other
204 template file in this folder as they represent the template variables. Change the
205 site URL and title, keywords, description, header and copyright as per your requirements
206 and save. Again, __DO NOT__ delete or edit anything within `{` and `}`.
208 Note that, BiaWeb2 relies on the `<base>` HTML tag to be present to generate the proper
209 links structure. There are, of course, pros and cons to using this tag, but at present,
210 this tag is required to generate a site with BiaWeb2.
212 __rss.tpl.xml__ and __rssitem.tpl.xml__ are required to generate the RSS feed for
213 each category (note that RSS feeds are generated only for documents/articles within that
214 category alone and not any sub-categories. This is a limitation at present).
216 Again, change the title, description and URL as required:
220 <?xml version="1.0" encoding="UTF-8" ?>
223 <!-- change title description and link as needed-->
224 <!-- don't touch anything within the curly braces -->
225 <title>My Site - {title}</title>
226 <description>Site Description</description>
227 <link>http://my.site</link>
228 <pubDate>{pubdate:%a, %d %b %Y %H:%M:%S %z}</pubDate>
237 <!-- change http://my.site to your actual site URL -->
238 <!-- don't touch anything within the curly braces-->
239 <link>http://my.site/{url}</link>
240 <guid>http://my.site/{url}</guid>
241 <pubDate>{pubdate:%a, %d %b %Y %H:%M:%S %z}</pubDate>
244 Change the URL part `http://my.site/` to your site's url (dont't remove the
245 `{url}` bit from the above)
247 That's it. Now your templates are set up to generate your website with proper links.
249 Though this process looks tedious, it is basically a one-time setup. Once your template is
250 configured, you almost never need to touch it again (unless you are changing the URL of
253 ### Generating the output
255 Now we can invoke `biaweb2` on your website source. To make invoking `biaweb2` convenient
256 make a small shell script called `gensite.sh` within `~/path/to/mywebsite` with the
260 /path/to/biaweb2/biaweb2 -i Home -t templates -o Out
262 and change it to executable (from the command line):
264 chmod +x ~/path/to/mywebsite/gensite.sh
266 Invoke the `gensite.sh` script from within the `~/path/to/mywebsite` directory:
270 You should get output similar to this
276 Generated in (s): 0.0848904
278 Assuming you have only one folder _Blog_ inside the _Home_ folder.
280 __Note__ that if you provide a trailing `/` to your input folder parameter `-i`
281 then the "base" node of your tree will not have any name - it will simply be
282 blank. Your output would look like this:
288 Generated in (s): 0.0848904
290 Use this "feature" as you wish.
292 That's it. You can now transfer the contents of the _Out_ folder to your web host
295 ### Updating your website
297 Simply make any changes to the source folder (by creating content files and folders) and
298 invoke the above shell script. BiaWeb2 will regenerate the entire tree, as it does not maintain
299 the state of any incremental updates. If you are making major changes, it is recommended that
300 you delete the output directory before re-generating, as this will be a "clean" build. Change
301 your `gensite.sh` script as below to ensure that the output directory is clean with no stale
302 content (i.e. removed files / folders from the source tree):
306 /path/to/biaweb2/biaweb2 -i Home -t templates -o Out
308 ### Recommendations for Uploading Content and Static Resources
310 Often, a website is more than just the HTML pages. You have images, for instance needed by
311 your pages. While BiaWeb2 does not handle static content, it's quite easy to deal with static
312 content, since they need to be uploaded to a fixed location on your website. The `gensite.sh`
313 script can be adapted to copy/sync your remote website with the generated output of BiaWeb2
314 as well as static resources by adding a couple of extra lines:
316 Assume that we keep our static resources (like images) in _images_ within the folder
317 _/path/to/mywebsite/images_. We can set the script to automatically sync the images
318 folder with your remote website (assumed to be accessible at `host@remote`).
323 /path/to/biaweb2/biaweb2 -i Home -t templates -o Out
325 # Sync contents of the Out folder with the remote site at host@remote
326 rsync -avrz --delete ~/path/to/mywebsite/Out/ host@remote:/path/to/www/
328 # Sync static resources such as images to remote website
329 rsync -avrz --delete /path/to/mywebsite/images/ host@remote:/path/to/www/images
331 The resources can then be linked from your individual pages with markdown like this
337 ![My image](images/testimage.jpg)
339 Since BiaWeb2 uses the `<base>` tag to define the base URL, the above code will work
340 from any location on your website.
342 ## Further Customization and Notes
344 * You can edit the contents of the _templates_ folder to get a more unique look and feel.
345 Templates are just plain HTML bits with no logic (other than the template vars marked
346 within curly braces). The __style.css.tpl__ file is the CSS bit that is embedded in
347 all pages of the site. At present there is no way to get a different look and feel for
348 different categories or parts of the site.
350 * The file __stringbits.txt__ contain general strings that are used to describe parts of
351 your website. This can also be customized, but each line stands for a particular item
352 and should not be interchanged. Ensure that changes to a particular line describe the
353 same item (in a different way). For example the text `List of Articles` may be substituted
354 by `List of Docs` or `Documents` but changing it to `Categories` will not make sense.
356 * The generated website from the default template should conform to HTML 5. If there are
357 any errors in the resultant HTML, please raise an
358 [issue](https://gitlab.com/harishankarv/biaweb2/-/issues/new) to
359 address it and it will be fixed. In general, please raise an issue for any bugs,
360 feedback or feature requests. However, as far as features are concerned, there is no
361 plan to make this a comprehensive website management tool. The key philosophy of this
362 tool is simplicity and I plan to keep it that way.
364 * __Limitation of RSS Feed:__ At present the RSS feed generated by the script in
365 __feed.xml__ does not fetch any articles from sub-categories and only fetches articles from'
366 its own category. This may be addressed in the future, depending on whether this is seen