Tutorial of BikiBikiBob

This article explains the format of article files, using examples for clarity.

Typical Article

Each article is typically a structured document that specifies a title. When used as a blog, the date is also usually specified. Additionally, it's a good idea to include headings for each section to make the content easier to read.

@title How to Brew Tea
@date 2024/05/11

I will explain how I learned to brew tea in England.

* Selecting Tea Leaves

To brew delicious tea, you first need to select the appropriate tea leaves, such as [[Darjeeling]].
...

The formatting of BikiBikiBlog articles is a blend of Wikipedia and Hatena Blog syntax, with some unique features. Anyway, it's very simple and easy to learn. This article covers almost all the functions. For now, you only need to remember the following syntax to start using it:

• Title: @title text
• Date: @date YYYY/MM/DD
• Heading: * text
• Paragraph: Just write normally. Separate paragraphs with a blank line.
• Link: [[Destination Title]], [Display Text|Destination Title]]
• Image: @image url

You can name article files using any string allowed by your operating system, but for practical purposes, it's best to use only alphanumeric characters and hyphens. Examples: "index.art", "hop-step-jump.art", "011-sodium.art". On the other hand, the title specified in the "@title" line can be any readable string.

Dates are specified in the "@date" line. For just a date, use the format "YYYY/MM/DD". To specify a date and time, use "YYYY/MM/DD hh:mm:ss". The timezone is not specified, and the date and time are interpreted based on the system's timezone.

Paragraphs

Lines that do not start with special characters like "@", "*", or "-" are considered normal paragraphs. A single line break within a paragraph is interpreted as a line break (HTML "<br/>"). Consecutive line breaks forming a blank line between them starts of a new paragraph.

This line and
this line are part of the same paragraph.

A blank line separates paragraphs.

You can[\n][\t]format text[\n][\t][\t]like this.

This line and
this line are part of the same paragraph.

A blank line separates paragraphs.

You can
   format text
      like this.

Leading spaces are ignored. If you need to start a normal paragraph with "@", "*", or "-", place a leading space at the beginning of the line. "[\n]" in the text also represents a linefeed. "[\t]" in the text represents a horizontal space.

HTML tags written within the article will be displayed as-is, without any functional meaning. To style text, use the special formatting described later.

Subheadings

Lines starting with "* " are subheadings (a space is required after the asterisk). Use "** " for sub-subheadings and "*** " for sub-sub-subheadings. Note that the main heading is the article's title.

* Subheadings
** Subsubheadings
*** Subsubsubheadings

Subheadings

Subsubheadings

Subsubsubheadings

Each subheading is assigned an HTML ID attribute, which can be used as an anchor link. In the ID value is the same as the heading text but spaces are replaced with underscores ("_"). If there are multiple identical IDs, a suffix "_2", "_3", etc., is added to the second and subsequent IDs. For example: "#Subheadings", "#Subheadings_2", "#Subsubheadings".

From a structured document perspective, the true main heading (<h1>) is the site's title at the top of the page, the article title is a subheading (<h2>), and subheadings within the article are subsubheadings (<h3>), and so on. Keep this in mind when customizing CSS. However, for general readers, it’s more intuitive to present the article title as the main heading. The default style displays the site title as a subtle annotation if an article title is present.

Bulleted Lists

Lines starting with "- " form bulleted lists (a space after the hyphen is required). Bulleted lists can be hierarchical. "- " represents the first level, "-- " the second level, "--- " the third level. Using "+" instead of "-" creates numbered lists. It's possible to switch between numbered and unnumbered lists at each level.

- First level
-- Second level
-- Second level
--- Third level
--- Third level
- First level
++ Second level
++ Second level

+ First level
++ Second level
++ Second level
+++ Third level
+++ Third level
+ First level
-- Second level
-- Second level

• First level
• Second level
• Second level
• Third level
• Third level
• First level
1. Second level
2. Second level

1. First level
1. Second level
2. Second level
1. Third level
2. Third level
2. First level
• Second level
• Second level

Hyperlinks

You can create hyperlinks between articles by enclosing any string in double square brackets, like "[[abcde]]". The link destination will be an article with the same title as the enclosed string. For example: Installation and Operations

Please start with [[Installation and Operations]] document.

To specify a different title for the link destination, write it after "|". For example: how to install

Please start with the document on [[how to install|Installation and Operations]].

If the link destination starts with "filename:", the linked article will be the one with that filename (without extension). For example: Installation method

Please start with the document on [[how to install|filename:001-installation]].

If the link destination starts with "http://" or "https://", the URL itself becomes the link destination. For example: example.com

We often use [[example.com|https://example.com/]] as an example domain.

If the link destination includes "#", the part after "#" becomes the fragment string of the URL, used for jumping to specific headings within the page. If the link starts with "#", it's used for jumping within the same page. Examples: Operating Environment, Hyperlinks, #Hyperlinks

Check [[Operating Environment|Installation and Operations#Prerequisites]] if something is wrong.
You can put [[Hyperlinks|#Hyperlinks]] in the article.
You can put [[#Hyperlinks]] in the article.

When linking by title, uppercase and lowercase letters are not distinguished. Thus, "Jim Beam" matches "jim beam", "JIM BEAM", and "jIm bEaM".

If multiple articles have the same title, suffixes like " (2)", " (3)" are automatically added in ascending order of filenames. A space is put before the bracket. Specify the target link like "Title (2)" for the second or later articles.

To easily link to Wikipedia articles in English, use the format "enwiki:xxx" and for Japanese Wikipedia, use "jawiki:xxx". If xxx is omitted, the anchor string is searched. Example: UNIX, ハイパーリンク

[[UNIX|enwiki:Unix]] and [[Linux|enwiki:]] are similar but different.
いつも[[細君|jawiki:妻]]は[[銭湯|jawiki:]]に出かける。

To easily link to the result of Google search, use the format "google:xxx". If xxx is omitted, the anchor string is searched. Example: OSS、Android

BikiBikiBob is [[OSS|google:open source software]] too.
We test it on [[Android|google:]] for mobile devices.

Other Text Decorations

Various text decorations can be applied to arbitrary strings within paragraphs, including bold, italic, underline, strikethrough, fixed width, ^superscript, _subscript, larger, and smaller.

This is [*bold*] and this is [/italic/].
This is [_underline_] and this is [-strikethrough-].
This is [#fixed width#], this is [^superscript^], this is [,subscript,].
This is [:larger:], this is [.smaller.].

You can also specify text colors like red, green, blue. Arbitrary colors like ABCDEF are also available by using hexadecimal numbers.

[{red:blood}], [{green:grass}], [{blue:ocean}]
[{#f00:blood}], [{#080:grass}], [{#00f:ocean}]

Ruby text annotations like "蒲生氏郷Gamo Ujisato" and "See the dermatologistskin doctor" can be added.

[(蒲生氏郷:Ujisato Gamo)] saw the [(dermatologist:skin doctor)].

Nested decorations are possible, e.g., Bold italic red link. Decorations can also be nested within anchors, e.g., ^hyper _link.

[*[/[{red:[[Bold italic red link|enwiki:Hyperlink]]}]/]*].
[[[^hyper^] [,link,]|enwiki:Hyperlink]]

To display nested decorations without nesting,

You can place special expressions directly within paragraphs by nullifying nesting, like [[UNIX]] and [[Linux]].

You distinguish [||[[UNIX]] and [[Linux]]||].

Text decorations and hyperlinks can be used in regular paragraphs, bulleted list items, and table cells but not in headings or preformatted text.

Images and Videos

You can embed images and videos as follows. For more details, please read the Images and Videos article.

@image https://dbmx.net/harunatsu-bg-lq.jpg
@video https://dbmx.net/bikibikibob/data/design-a.mov

You can also embed videos from YouTube.

@youtube https://www.youtube.com/watch?v=Hln6MoTKnUc

Google Maps can also be embedded.

@maps Tokyo Skytree

Preformatted Text

If you want to display whitespace characters or line breaks exactly as they are, it's recommended to use preformatted text, which corresponds to the HTML <pre> element. The text between lines starting with ">||" and "||<" will be displayed as preformatted text.

>||
#include <stdio.h>

int main(int argc, char** argv) {
  printf("Hello, World!\n");
  return 0;
}
||<

Additionally, starting with ">>||" instead of ">||" will make the preformatted text continue until "||<<".

Tables

When you want to present structured data in a concise manner, using tables is a good choice. It correspond to HTML <table> element. Lines starting with "|" in succession are treated as a table, where each line becomes a row, and columns are separated by "|".

|^Name|^Category|^Diameter|^Mass|^Gravity|^Distance from Sun
|Mercury|{2}Inner Planet|#4879 km|#0.33*e24 kg|#3.7 m/s^2|#57.9*e6 km
|Venus|#12104 km|#4.87*e24 kg|#8.9 m/s^2|#108.2*e6 km
|Earth|-|#12756 km|#5.67*e24 kg|#9.8 m/s^2|#149.6*e6 km
|Mars|Outer Planet|#6792 km|#0.64*e24 kg|#3.7 m/s^2|#228.0*e6 km
|<4>(From Wikipedia)|<2>(According to NASA)

If the text inside a cell is specified in the format "<n>", the cell will be horizontally merged as if it had a "colspan" attribute with the specified number. Similarly, if the text inside a cell is specified in the format "{n}", the cell will be vertically merged as if it had a "rowspan" attribute with the specified number.

If a cell's content starts with "#", the cell's content is considered a number and displayed right-aligned and in a fixed-width font. If a cell's content starts with "^", the cell's background color changes. If you want to disable the special characters at the beginning of a cell's content, prepend a space.

If a cell's content starts with "<=>", the width of the cell is set as the page width divided by the number of columns. If all cells have it, multicolumn layout is realized. If you want to put linefeed in the cell, use "[\n]".

|<=>^Original|<=>^Translation
|<=>Deutschland, Deutschland über alles,[\n]Über alles in der Welt.[\n]Wenn es stets zu Schutz und Trutze,[\n]Brüderlich zusammenhält.[\n]Von der Maas bis an die Memel,[\n]Von der Etsch bis an den Belt.[\n]Deutschland, Deutschland über alles,[\n]Über alles in der Welt!|<=>Germany, Germany above all,[\n]Above all in the world.[\n]When it always, for protection and defence,[\n]Brotherly stands together.[\n]From the Meuse to the Neman,[\n]From the Adige to the Little Belt.[\n]Germany, Germany above all,[\n]Above all in the world.

Indented Paragraphs

Paragraphs starting with "> " (requires a space after the greater-than sign) are indented when displayed. Additionally, paragraphs starting with ">> " have a darker background along with indentation. The interpretation of these levels of indentation depends on the context; they can be used as columns or for block quotes. You can also increase the indentation further with ">>> " and ">>>> ".

> Indent Level 1
Just indented, with no change in background color.

>> Indent Level 2
Indented with a darker background.

>>> Indent Level 3
Just indented, with no change in background color.

>>>> Indent Level 4
Indented with a darker background.

Indent Level 1
Just indented, with no change in background color.

Indent Level 2
Indented with a darker background.

Indent Level 3
Just indented, with no change in background color.

Indent Level 4
Indented with a darker background.

Embedded Columns

Paragraphs starting with "[!caption!]" are displayed as columns (enclosed articles) with the specified caption. Columns usually contain content or supplementary information that is independent of the main article. Since these are considered as paragraphs, they continue until an empty line is encountered.

[!The Teachings of Tokugawa Ieyasu!]
Life is like a journey carrying a heavy load on a long road. Don't hurry.
If you consider inconvenience as normal, you will not feel lacking.
When desires arise, remember times of hardship.
Patience is the foundation of lasting peace, and anger should be seen as the enemy.
Knowing only victory without knowing defeat will bring harm upon oneself.
Do not blame yourself and do not blame others.
Being less than needed is better than having too much.

To create a hidden column that is initially concealed when the page is loaded, prefix the caption with "~". This can be useful for spoiler alerts, quiz hints, or answers.

[!~Quotes by Thomas Edison!]
Genius is one percent inspiration, ninety-nine percent perspiration.
I have not failed. I've just found 10,000 ways that won't work.
There are no rules here -- we're trying to accomplish something.
When you have exhausted all possibilities, remember this - you haven't.

Horizontal Lines

To separate sections of an article without using headings, horizontal lines are handy. A line with just two hyphens is a level 0 horizontal line, which is transparent. Lines with three to five hyphens create level 1 to 3 horizontal lines, with varying width, color, and margin. Horizontal lines also clear text wrapping around images.

Above a level 0 horizontal line. ABCDEFG. one two three. 123456789.
--
Above two consecutive level 0 horizontal lines. HIJKLMN. four five six. 123456789.
--
--
Abobe a level 1 horizontal line. OPQRSTUV. seven eight nine. 123456789.
---
Abobe a level 2 horizontal line. WXYZ1234. ten eleven twelve. 123456789.
----
Abobe a level 3 horizontal line. 567890ABC. thirteen fourteen fifteen. 123456789.
-----
Below the level 3 horizontal line. DEFGHIJK. sixteen seventeen eighteen. 123456789.

Above a level 0 horizontal line. ABCDEFG. one two three. 123456789.

Above two consecutive level 0 horizontal lines. HIJKLMN. four five six. 123456789.

Abobe a level 1 horizontal line. OPQRSTUV. seven eight nine. 123456789.

Abobe a level 2 horizontal line. WXYZ1234. ten eleven twelve. 123456789.

Abobe a level 3 horizontal line. 567890ABC. thirteen fourteen fifteen. 123456789.

Below the level 3 horizontal line. DEFGHIJK. sixteen seventeen eighteen. 123456789.

Table of Contents of the Article

For lengthy articles, it's beneficial to create a table of contents to navigate through different sections of the article.

* Table of Contents

@page-toc

* Introduction

I am a cat. I have no name yet. ...

The table of contents for this page will look like this:

• Typical Article
• Paragraphs
• Subheadings
• Subheadings
• Subsubheadings
• Subsubsubheadings
• Bulleted Lists
• Hyperlinks
• Other Text Decorations
• Images and Videos
• Preformatted Text
• Tables
• Indented Paragraphs
• Embedded Columns
• Horizontal Lines
• Table of Contents of the Article
• Site-wide Table of Contents
• Tags and Cross-references
• Miscellaneous Attributes

Site-wide Table of Contents

You can also create a table of contents for articles across the site. Use the following format. The "order" option specifies the order of sorting, which can be "title" (default), "date", or "filename". If the "reverse" option's value is "true", it will be sorted in reverse order. The maximum number of items to display can be specified with the "max" option.

For example, to display a list of the latest articles on a blog-style site:

@site-toc [order=date] [reverse=true] [max=10]

For a site where articles are meant to be read sequentially, numbering the filenames (e.g., "001-installation.art") and using the default filename order in the table of contents is recommended.

@site-toc [order=filename]

For a site like a wiki, where there are many articles gathered without a specific order, creating a table of contents based on titles is a good approach.

@site-toc [order=title]

The table of contents for this tutorial will look like this:

Tags and Cross-references

If there are common themes shared among several articles, it's useful to organize each article with tags. Use lines starting with "@tags" followed by comma-separated tags to specify tags. Tag names can contain any characters except commas. Uppercase and lowercase letters are distinguished.

@tag Cycling, Brompton, @Yokohama-Kanagawa

Articles with tags will automatically have cross-references to other articles with the same tags appended at the end. Clicking on displayed tags will show a list of articles containing those tags.

Placing a line "@site-tags" in an article embeds a list of all site tags.

@site-tags

tutorial (5)

Installation and Operations , Article Formatting , Images and Videos , Customization , File Management on the Browser

@Kamakura (2)

Traveling in Kamakura , Hato Sable

installation (2)

Customization , File Management on the Browser

format (1)

Article Formatting

formatting (1)

Images and Videos

install (1)

Installation and Operations

souvenir (1)

Hato Sable

travel (1)

Traveling in Kamakura

A tag used by only one article is not very useful. Therefore, it's recommended to start tagging when you have two or more articles with the same tag. However, tags that represent place names, personal names, or version numbers have intrinsic meanings, so it's fine to use them as needed. It's also a good idea to distinguish them by prefixing with "#" or "@" or "$".

Miscellaneous Attributes

Lines starting with "@misc" can specify special instructions for articles. Options include "noshare" (to disable sharing), "nocomment" (to disable comments), "notoc" (to exclude from site-wide table of contents), and "nosearch" (to exclude from full-text search). Multiple options can be specified with comma separation.

@misc noshare, nocomment, notoc, nosearch

It's not ideal for the site's homepage or the table of contents page to be included in the table of contents. Therefore, it's a good practice to add the "notoc" attribute to those articles. Articles with the "notoc" attribute are also excluded from the "previous" and "next" link structure.

When writing a new article while the site is running, it's convenient to specify only the filename of that article when running the generator for preview purposes without updating other articles. Additionally, adding the "notoc" attribute as a precaution prevents it from being reflected in the table of contents or other links even when the generator is run without specifying the article filename.