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
- Second level
- Second level
- First level
- Second level
- Second level
- Third level
- Third level
- 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 "
[(蒲生氏郷: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)
Name | Category | Diameter | Mass | Gravity | Distance from Sun |
Mercury | 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 |
(From Wikipedia) | (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.
Original | Translation |
Deutschland, Deutschland über alles, Über alles in der Welt. Wenn es stets zu Schutz und Trutze, Brüderlich zusammenhält. Von der Maas bis an die Memel, Von der Etsch bis an den Belt. Deutschland, Deutschland über alles, Über alles in der Welt! | Germany, Germany above all, Above all in the world. When it always, for protection and defence, Brotherly stands together. From the Meuse to the Neman, From the Adige to the Little Belt. Germany, Germany above all, 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
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.