This article explains how to install and operate BikiBikiBob.
Prerequisites
It is assumed that you are running a UNIX-based OS (Linux, MacOS, FreeBSD, Solaris, etc.) with any web server (Apache, Nginx, etc.) and have Python3 available. Python version 3.8 or higher is required. No other modules or libraries are needed.
Download
Run the following command to download the BikiBikiBob program and data. If the "git" command is not installed, download it from the public repository webpage.
$ git clone https://github.com/estraier/bikibikibob.git
Installation
The core of BikiBikiBob is a single command "bbb_generate.py". Place this command in a directory that is in your execution path. For example, to place it in "/usr/local/bin", do the following:
$ cd bikibikibob $ sudo cp bbb_generate.py /usr/local/bin
If you do not have root privileges, you can place it somewhere under your home directory or run the file directly from the repository.
Web Server Operation
Make sure your web server is running. For example, let's say you place the files for your blog site in "/home/mikio/public/bikibikibob/myblog". Ensure that the HTML or XHTML files placed there are properly served.
Preparing Articles
For example, let’s place the input data for your site in "/home/mikio/myblog/input". Create this directory and copy the contents of the "input" directory from the downloaded repository into it:
$ mkdir -p /home/mikio/myblog/input $ cp input/* /home/mikio/myblog/input
Configuration File
Edit "bbb.conf" in the input directory you created. By default, it contains the following:
input_dir: . output_dir: /home/mikio/public/bikibikibob/myblog script_file: bbb.js style_file: bbb.css site_url: https://dbmx.net/bikibikibob/myblog/ title: My Blog subtitle: loving coffee and bicycles language: en extra_meta: author|Mikio Hirabayashi extra_meta: keywords|coffee, bicycle extra_meta: robots|all step_order: date
At the very least, you need to change "output_dir" and "site_url" to match your site. Paths can be specified as relative paths to the directory where "bbb.conf" is located or as absolute paths from the root directory.
Running the Generator
Run the following command to convert article files into HTML files:
$ bbb_generate.py --conf /home/mikio/myblog/input/bbb.conf
All files in the input directory with the extension ".art" will be treated as article files. They will be converted to HTML and saved in the output directory.
Verify that HTML files have been generated in "/home/mikio/public/bikibikibob/myblog" and access "index.xhtml" with a web browser.
Adding files with the ".art" extension to "/home/mikio/myblog/input" will treat them as new articles. For example, write the following content in a file named "sample-1.art"to create a sample article. For details on formatting, see Article Formatting.
@title Sample 1 @date 2024/05/25 This is a [*sample*].
After adding new article files or editing existing ones, run the generator again to regenerate the HTML:
$ bbb_generate.py --conf /home/mikio/myblog/input/bbb.conf
Confirm that the new article is reflected in the list of recent articles on the top page.
The new article is rendered like below. In the same way, you add new articles and edit existing articles.
When you run the generator, files in the output directory and with the ".xhtml" extension and having the line '<meta name="generator" content="BikiBikiBob"/>' are removed. "bbb.css" and "bbb.js" are overwritten by the files specified in the configuration file. All other files are left untouched. And, HTML files corresponding to the article files in the input directory are regenerated.
If you do not specify the "--conf" option, the generator will try to use "bbb.conf" in the current directory as the configuration file. Therefore, you can omit the "--conf" option when working within the input directory.
$ cd /home/mikio/myblog/input $ bbb_generate.py
To update only the HTML file corresponding to a specific article file, specify the article file name. The extension is optional, and you can specify multiple articles too.
$ bbb_generate.py sample1
When you specify article names, other articles are not updated, and the index and inter-article hyperlinks are not affected. Therefore, after finishing the editing of articles, you should run the generator without specifying article names to update the entire site.
$ bbb_generate.py
During the editing process, if you generate HTML for preview by specifying article names, the new articles will not be visible from other articles. This can be used as a draft function. To temporarily hide an article, remove or comment out the "@title" and "@date" tags, and then run the generator.
To delete unnecessary article files, simply use the "rm" command. The corresponding HTML files will be removed the next time the generator is run. You can change file names or titles freely, but be aware of possible broken links from other articles. If broken links are detected, warnings will be shown during generator execution, allowing you to address them as needed.
Customization
You can easily change the appearance of your site by editing "bbb.css", the stylesheet, or modify the dynamic UI behavior by editing "bbb.js", the JavaScript code. These files are copied from the input directory to the output directory each time the generator is run, so make changes to the files in the input directory.
For advanced customizations such as share functions, comment functions, or search functions, see the Customization article.
For functionality to upload data, edit articles, or update the site via the browser, see the File Management on the Browser article.