This article explains how to customize a site running on BikiBikiBob.
Basic Site Settings
The URL of the site you are operating serves as the starting point for various links within the site, so it needs to be set appropriately. Clicking on the site's banner on each page will direct you to this URL.
site_url: https://dbmx.net/bikibikibob/myblog/
It is common to configure the web server to display a specific file within the specified directory as the homepage, such as "index.art" corresponding to "index.xhtml". You can designate a different file as the homepage if preferred. If the web server cannot specify a homepage, you can directly specify the file of the homepage as shown below.
site_url: https://dbmx.net/bikibikibob/myblog/index.xhtml
The site title and subtitle are set in the configuration file. The title is required as it is used for the HTML <title> element and the <h1> element. The <title> element of each article will be in the format "Site Title: Article Title". The subtitle is displayed modestly below the <h1> element and can be omitted.
title: The Powerpuff Girls subtitle: Suger, Spice, and Everything Nice
The language setting is also specified in the configuration file. This is reflected in the "lang" attribute of the HTML <html> element. It is used by browsers to select the appropriate font and by screen readers to choose the correct model, so it should be set appropriately.
language: en
There is an "extra_meta" item in the configuration file. The settings written here become HTML <meta> elements. They are mainly used to control automated user agents like search engines and can also be used for Google Search Console site verification.
extra_meta: author|Craig McCracken extra_meta: keywords|cartoon, animation, comedy, superhero extra_meta: description|a fan site of an American superhero animation The Powerpuff Girls extra_meta: robots|all extra_meta: google-site-verification|dD_zZjUMXjtRjsnDHZCAsMGutwUWrfm48cVUDJtwFDK
These meta elements are optional and can be omitted entirely. However, it is advisable to set them appropriately for SEO purposes.
If you want to put arbitrary HTML code in the page, set the following configurations in "bbb.conf". The content of the file specified by "extra_head_file" is inserted in the <head> element. The content of the file specified by "extra_body_header_file" is inserted just after the <body> tag. The content of the file specified by "extra_body_footer_file" is inserted just before the </body> tag.
extra_head_file: bbb-extra-head.html extra_body_header_file: bbb-extra-body-header.html extra_body_footer_file: bbb-extra-body-footer.html
Step Link Feature
The step link feature automatically adds "Previous" and "Next" links at the bottom of articles. To enable step links, specify the order in the configuration file.
step_order: date
By default, it is set to "date", which targets only articles with the @date attribute and allows readers to navigate in chronological order. This is suitable for operating the site in a blog-like manner.
If you specify "title" for the order, it targets only articles with the @title attribute, allowing readers to navigate in alphabetical order of the titles. As you can give numbers to the titles like "001: Introduction", you can arrange the order as you like. If you want readers to follow the articles in a specific order, such as in a book, this method is appropriate.
Specifying "filename" for the order targets all articles and allows navigation in alphabetical order of the filenames. This is useful if you do not want to include numbers in the titles.
If "step_order" is omitted, the step link feature is disabled. This might be suitable for operating the site in a wiki-like manner.
Table of Contents Feature
Writing a line starting with "@site-toc" in an article creates a table of contents for the entire site. This is a list of links to each article in a specific order. Typically, the index is placed in an article that will be the site's homepage, such as "index.art".
For a blog-like operation, you might place an index with a heading like "Latest Articles" and list the articles in reverse chronological order.
* Latest Articles @site-toc [order=date] [reverse=true] [max=10]
For a book-like operation, you might place an index with a heading like "Table of Contents" and list the articles in ascending order of the titles. In this case, write the titles in the format "001: Installation" to align the desired order with the alphabetical order of the titles.
* Table of Contents @site-toc [order=title]
If you do not want to include numbers in the titles, you can number the filenames like "001-installation.art" and list the index by filenames.
* Table of Contents @site-toc [order=filename]
Including the index article in the table of contents would look awkward. Specify the "notoc" attribute for articles you want to exclude from the table of contents. Articles with "notoc" are also excluded from the step link targets.
@misc notoc
The actual table of contents will be displayed as follows.
SNS Share Feature
Enabling the SNS share feature in the configuration file adds buttons to share each article on various social networks. It supports Twitter (X), Line, Facebook, and Hatena Bookmark.
share_button: twitter share_button: line share_button: facebook share_button: hatena
If you do not want to include share buttons in a specific article, write the following line in the article.
@misc noshare
When you share an article, a description text and an eye catcher image are shown as well as the article title. By default, text at the beginning of the page is used as the description, and the first image in the article is used as the eye catcher. You can explicitly specify the description by writing a line beginning with "@desc". You can also explicitly specify the eye catcher by adding "[top]" parameter to an image.
@title Jim Beam @desc Distilling to a time honored family recipe since 1795 @image https://example.com/mediocre.jpg @image https://example.com/superb.jpg [top]
Attributes such as title are expressed as HTML meta data based on OGP. However, at this point, Twitter doesn't properly read data of XHTML's MIME type (application/xhtml+xml). To support Twitter, you have to send XHTML with HTML's MIME type (text/html). Although it's ok to send all XHTML as HTML, it's better to do it only for Twitter bot. With Apache2, you'll write the follwoing directives in .htaccess.
<Files ~ "(\.(xhtml)$)|(^$)"> SetEnvIf User-Agent "Twitterbot/" ua_html_only Header set Content-Type "text/html; charset=UTF-8" env=ua_html_only </Files>
Moreover, to show descriptions and images of shared articles on Twitter, write the following in "bbb.conf".
extra_meta: twitter:card|summary_large_image extra_meta: twitter:site|@youraccountname extra_meta: twitter:creator|@youraccountname
Comment Feature
You can allow readers to leave comments on each article. To enable the comment feature, you need to set up a CGI script for comment management. Copy "bbb_comment.cgi" from the downloaded repository to a directory where CGI scripts can be executed.
Edit the installed "bbb_comment.cgi" to specify the locations of the HTML files and the comment files. Create the directory for the comment files in advance and set permissions so the CGI script can read and write. Since the comment files will include the client's IP address, control access to ensure they are not publicly accessible.
HTML_DIR = "/home/mikio/public/bikibikibob/myblog" COMMENT_DIR = "/home/mikio/myblog/comment"
You can also write the paths as relative paths from the directory where the CGI script is located. Therefore, if you place the CGI script in the same location as the HTML files, you can write it as follows.
HTML_DIR = "." COMMENT_DIR = "/home/mikio/myblog/comment"
Specify the URL of the installed script in "bbb.conf". If you place it in the same location as the HTML files, write it as a relative URL, just the filename.
comment_url: bbb_comment.cgi
The comment button attached below each article shows the current number of comments. It is gray if there are no comments, light green if there are comments, and light pink if the latest comment was posted within the last 48 hours.
It can be cumbersome to check which articles have comments, so there is a feature to list the latest comments across all articles. Write the following line in an article where you want to display this list.
@comment-history [max=100] [perpage=20]
The actual comment history will be displayed as follows.
Comment data is separated by article and saved with the extension changed to ".cmt" from the article file name. The total capacity of the comment data for each article is 1MB. If exceeded, writing is prohibited. The history file is saved as "__cmthst__.tsv". Its total capacity is 256KB, and if exceeded, old history entries are deleted. These thresholds are written at the beginning of "bbb_comment.cgi" and can be changed as desired.
If you need to edit or delete comments, open the comment file with a suitable editor. If you receive a large amount of spam, use "grep -v" or something to filter based on IP address or author name.
Full-Text Search Feature
You can add a full-text search feature to search the content of each article (title, date, and body). To enable the full-text search feature, set up a CGI script for search. Copy "bbb_search.cgi" from the downloaded repository to a directory where CGI scripts can be executed.
Edit the installed "bbb_search.cgi" to specify the location of the HTML files.
HTML_DIR = "/home/mikio/public/bikibikibob/myblog"
You can also write the path as a relative path from the directory where the CGI script is located. Therefore, if you place the CGI script in the same location as the HTML files, you can write it as follows.
HTML_DIR = "."
Specify the URL of the installed script in "bbb.conf". If you place it in the same location as the HTML files, write it as a relative URL, just the filename.
comment_url: bbb_comment.cgi
Write the following line in the article where you want to place the search box. When the generator is run in this state, a search box will be placed at that location.
@search [max=100] [perpage=10]
The actual display will be as follows. Try entering queries such as "file" or "Kamakura".
If you do not want to include a specific article in the search results, specify the "nosearch" attribute for that article. Usually, it is better to exclude the homepage from the search results.
@misc nosearch
Feature to Hoard External Data
You might want to embed images or videos from external image management services like Google Photos in your articles. However, most commercial services do not provide permanent links to managed data, so you cannot directly reference them in your articles. Nonetheless, as long as the images can be viewed in a web browser, they generally have URLs. Thus, you can embed these temporary URLs in your article and then download the embedded images to your server and rewrite the URLs accordingly.
This method saves the bother of manually downloading and re-uploading image data, significantly enhancing the efficiency of writing articles that use many images. Additionally, if you only store the images embedded in your articles on your server, you don't need to manage all the photos and videos you take daily on your server.
To enable the automatic hoarding feature for external data embedded in your articles, include the following content in "bbb.conf":
hoard_target_url: ^https://[^/]*\.googleusercontent.com/ hoard_local_url: https://dbmx.net/bikibikibob/myblog/data/ hoard_data_dir: /home/mikio/myblog/data
"hoard_target_url" sets a regular expression that matches the URLs of images or videos to be acquired. If you want to specify multiple services, you can write multiple lines of "hoard_target_url". For Google Photos, it should matche URLs of the domain "googleusercontent.com". "hoard_local_url" is the prefix string for the data published on your server. "hoard_data_dir" specifies the directory path where the acquired data is placed. This directory must be accessible by the web server, and the URL for this is specified by "hoard_local_url".
When you write an article embedding data from external services using the @image or @video notation, run the HTML generator with the "--hoard" option.
$ bbb_generate.py --conf /home/mikio/myblog/input/bbb.conf --hoard
When you do this, if the target external URL is found in the article being processed, the data will be acquired and saved, and the URL in the article will be rewritten to the URL of the saved data. If you run the same command again, the URL will already have been rewritten, so the data will not be acquired twice. Therefore, it is fine to always use the "--hoard" option in regular operations. However, if you decide not to use the saved data while writing an article, it will be wasted, so it is more efficient to preview the article without the "--hoard" option while writing, and then use the "--hoard" option to store the data when the article is completed.
Note that you have to make a small twist to get the URL of images in Google Photos. View each image, select its share button, select "Create link", and go to the destination page. Then, view the image there and right-click to select "Copy Image Address" of it.