BikiBikiBobのチュートリアル

最もミニマリストなCMSの導入と運用

記事の書式

記事ファイルの書式について、例を交えながら説明します。

典型的な記事

各記事は構造化文書の体裁を取り、タイトルを指定するのが普通です。ブログとして使う場合、日付も指定するのが普通です。また、内容のまとまり毎に見出しも書いて分かりやすくした方が良いでしょう。

@title 紅茶の淹れ方
@date 2024/05/11

私がイギリスで学んだ紅茶の淹れ方を説明します。

* 茶葉の選定

おいしい紅茶を入れるには、まず[[適切な茶葉|ダージリン]]を選ぶ必要があります。
...

BikiBikiBlogの記事の書式はWikipedia記法とはてなブログ記法の折衷ですが、独自の仕様もあります。いずれにせよ、非常に簡素なので、習得するのも容易でしょう。この記事だけでほぼ全ての機能を説明できます。差し当たっては、以下の記法だけ覚えれば使い始められるでしょう。

記事のファイル名は、OSが許すならどんな文字列でも良いのですが、実務上は英数字とハイフンだけを使うのが無難です。"index.art" とか、"hop-step-jump.art" とか、"011-sodium.art" とかです。一方で、@titleの行で記述するタイトルは分かりやすければどんな文字列でも良いです。

日付は@dateの行で指定します。日付だけを指定するなら"YYYY/MM/DD" の形式で、日付と時刻を指定するなら "YYYY/MM/DD hh:mm:ss" の形式にします。タイムゾーンは記述せず、日時の値はシステムのタイムゾーンに基づいて解釈されます。

段落

"@" や "*" や "-" などの特殊な文字で始まらない行は、普通の段落になります。単一の改行は、段落内での改行(HTMLの<br/>)になります。改行を連続させて空行を挟んだ場合、それは段落の区切りになります。

この行と
この行は、一つの段落です。

空行を挟むと、段落が分けられます。

行頭の空白は無視されます。通常の段落を "@" や "*" や "-" で始めたい場合、行頭に空白を置いてください。

記事の中にHTMLタグを書いてもそのまま表示されるだけで、タグとしての意味は持ちません。文字を装飾したい場合は後述する特殊記法を使ってください。

小見出し

"* " で始まる行は小見出しになります(星印の直後に空白が必要)。"** " で小小見出し、"*** " で小小小見出しも作れます。なお、大見出しは記事のタイトルです。

* 小見出し
** 小小見出し
*** 小小小見出し

小見出し

小小見出し

小小小見出し

各小見出しにはHTMLのID属性が振られ、ページ内リンクのリンク先にすることができます。IDの値は小見出しの文字列の空白を"_"に置換したものです。同名のIDが複数ある場合、2番目以降には "_2"、"_3" のような接尾辞が自動的につけられます。例:#小見出し#小見出し_2#小小見出し

構造化文書の観点で厳密に言うと、真の大見出し(<h1>)はページ冒頭のサイトタイトルであり、記事のタイトルは小見出し(<h2>)になり、記事内の見出しは小小見出し(<h3>)以降になります。CSSのカスタマイズをする際には留意してください。しかし、一般の読者にとっては記事のタイトルを大見出しとして表現する方が分かりやすいでしょう。上述の説明ではその考えに基づいて記事のタイトルを大見出しと書きました。なお、デフォルトのスタイルでは、記事のタイトルが存在する場合には、サイトタイトルはあたかも注釈のように控えめに表示されるようになっています。

箇条書き

"- " で始まる連続した行は箇条書きになります(ハイフンの直後に空白が必要)。箇条書きは階層構造にすることもできます。"- " は第1階層で、"-- " は第2階層で、"--- " は第3階層です。"-" の代わりに "+" を使うと、番号付きの箇条書きになります。階層毎に番号無しと番号付きを切り替えることもできます。

- 第1階層
-- 第2階層
-- 第2階層
--- 第3階層
--- 第3階層
- 第1階層
++ 第2階層
++ 第2階層

+ 第1階層
++ 第2階層
++ 第2階層
+++ 第3階層
+++ 第3階層
+ 第1階層
-- 第2階層
-- 第2階層
  1. 第1階層
    1. 第2階層
    2. 第2階層
      1. 第3階層
      2. 第3階層
  2. 第1階層

ハイパーリンク

"[[あいうえお]]" のように二重の角括弧で任意の文字列を囲むことで、記事間にハイパーリンクを貼ることができます。リンク先は、囲んだ文字列と同名のタイトルを持つ記事になります。

最初に[[インストール]]方法について学んでください。

囲んだ文字列とリンク先のタイトルを違うものにしたい場合、"|" の後にリンク先のタイトルを書きます。例:インストール方法

最初に[[インストール方法|インストールと運用]]について学んでください。

リンク先が "filename:" で始まる場合、そのファイル名(拡張子は不要)の記事がリンク先になります。例:インストール方法

最初に[[インストール方法|filename:001-installation]]について学んでください。

リンク先が "http://" か "https://" で始まる場合、そのURLがそのままリンク先になります。例:example.com

ドメインの例として[[example.com|https://example.com/]]がよく使われます。

リンク先が "#" を含む場合、その後ろはURLのフラグメント文字列になます。フラグメント文字列は該当ページ内の特定の見出しに飛ぶために使われます。リンク先が "#" で始まっていれば、同一ページ内の見出しに飛ぶために使われます。例:動作環境ハイパーリンク#ハイパーリンク

うまく動かない場合、[[動作環境|インストールと運用#前提条件]]を確認してください。
記事には[[ハイパーリンク|#ハイパーリンク]]を貼ることができます。
記事には[[#ハイパーリンク]]を貼ることができます。

タイトルでリンクを貼る場合、英字の大文字と小文字は区別されません。例えば、"Jim Beam" は "jim beam" にも "JIM BEAM" にも "jIm bEaM" にも該当します。

複数の記事が同じタイトルを持っていた場合、ファイル名の昇順で後になるものには、" (2)"、" (3)" などの接尾辞が自動的につけられます。括弧の前には空白が入ります。2番目以降の記事にリンクを貼る際には "Jim Beam (2)" などをリンク先として指定してください。

Wikipedia英語版の記事に簡単にリンクを貼るには、リンク先を "enwiki:xxx" の書式で書きます。同様にしてWikipedia日本語版に対しては、"jawiki:xxx" とします。xxxの部分を省略すると、アンカー文字列が検索対象になります。例:UNIXハイパーリンク

[[UNIX|enwiki:Unix]]と[[Linux|enwiki:]]は似て非なるものです。
いつも[[細君|jawiki:妻]]は[[銭湯|jawiki:]]に出かける。

その他の文字装飾

段落内の任意の文字列に対して、太字(<b>)斜体(<i>)下線(<u>)打ち消し線(<s>)固定幅(<kbd>)上付き(<sup>)下付き(<sub>)大きめ(<big>)小さめ(<small>)、の装飾が可能です。

これは[*太字*]で、これは[/斜体/]です。
これは[_下線_]で、これは[-打ち消し線-]です。
これは[#固定幅#]で、これは[^上付き^]で、これは[,下付き,]です。
これは[:大きめ:]で、これは[.小さめ.]です。

などの文字色も指定できます。16進数で指定してにもできます。

[{red:赤}]、[{green:緑}]、[{blue:青}]
[{#f00:赤}]、[{#080:緑}]、[{#00f:青}]

蒲生氏郷がもううじさと」「本気マジで恋する5秒前」「See the dermatologist皮膚科の専門医.」のようにルビを振ることもできます。

[(蒲生氏郷:がもううじさと)]、[(本気:マジ)]で恋する5秒前
[(dermatologist:皮膚科の専門医)]

装飾を入れ子にすれば、太字で斜体で赤いリンクなども表現できます。ハイパーリンクのように、アンカーの中に装飾を入れることもできます。

[*[/[{red:[[太字で斜体で赤いリンク|jawiki:ハイパーリンク]]}]/]*]
[[[^ハイパー^][,リンク,]|jawiki:ハイパーリンク]]

装飾が入れ子にするのを止めて、中身のそのまま文字列を表示することもできます。[[信長|織田信長]]のように、特殊表現をそのまま段落中に配置できます。

リンクは "[||[[アンカー文字列|リンク先]]||]" の書式で書きます。

ハイパーリンクや文字装飾は普通の段落と箇条書きの項目と表のセルにある文字列で使えます。見出し内の文字列や整形済みテキスト内の文字列では使えません。

画像と動画

画像と動画は以下のように貼り付けることができます。詳細については画像と動画の記事をご覧ください。

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

Youtube上の動画も埋め込めます。

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

Google Mapsの地図も埋め込めます。

@maps 東京スカイツリー

整形済みテキスト

空白や改行等をそのまま表示したい場合には、HTMLのpre要素になる整形済みテキストを使うと良いでしょう。">||" の行と "||<" の行の間が整形済みテキストになります。

>||
#inluce <stdio.h>

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

なお、">||" の代わりに ">>||" で始めると、"||<<" までが整形済みテキストになります。

構造化されたたくさんのデータをまとめて表示したい場合、HTMLのtable要素になる表を使うと良いでしょう。"|" で始まる連続した行は表として扱われ、各行が表の行になり、列は "|" で区切ります。

|^名前|^分類|^直径|^質量|^重力|^太陽との距離
|水星|{2}内惑星|#4879 km|#0.33*e24 kg|#3.7 m/s^2|#57.9*e6 km
|金星|#12104 km|#4.87*e24 kg|#8.9 m/s^2|#108.2*e6 km
|地球|-|#12756 km|#5.67*e24 kg|#9.8 m/s^2|#149.6*e6 km
|火星|外惑星|#6792 km|#0.64*e24 kg|#3.7 m/s^2|#228.0*e6 km
|<4>(Wikipediaより)|<2>(NASA調べ)
名前分類直径質量重力太陽との距離
水星内惑星4879 km0.33*e24 kg3.7 m/s^257.9*e6 km
金星12104 km4.87*e24 kg8.9 m/s^2108.2*e6 km
地球-12756 km5.67*e24 kg9.8 m/s^2149.6*e6 km
火星外惑星6792 km0.64*e24 kg3.7 m/s^2228.0*e6 km
(Wikipediaより)(NASA調べ)

セルの中の文字が "<n>" の書式で数値を指定している場合、colspan属性のように、セルがその数だけ横方向に結合されます。同様にして "{n}" の書式で数値を指定している場合、rowspan属性のように、セルがその数だけ縦方向に結合されます。

セルの中の文字列が "#" で始まっている場合、そのセルの文字列は数値とみなして右詰めかつ固定幅フォントで表示されます。セルの中の文字列が "^" で始まっている場合、そのセルは背景色が変わります。セルの文字列の先頭の特殊文字を無効化したい場合、空白を前置してください。

凹み段落

段落が "> " で始まる場合(不等号の直後に空白が必要)、その段落は右側に凹んで表示されます。また、">> " で始まる場合、凹んだ上に、背景色がやや暗くなります。それらにどのような意味を持たせるかは、内容次第です。コラム的に使っても良いですし、引用文を凹ませることにしても良いでしょう。さらに凹みの度合いを高くした ">>> " と ">>>> " も使えます。

> 凹みレベル1
凹むだけで、背景色は変わらない。

>> 凹みレベル2
凹んだ上に、背景色が変わる。

>>> 凹みレベル3
凹むだけで、背景色は変わらない。

>>>> 凹みレベル4
凹んだ上に、背景色が変わる。

凹みレベル1
凹むだけで、背景色は変わらない。

凹みレベル2
凹んだ上に、背景色が変わる。

凹みレベル3
凹むだけで、背景色は変わらない。

凹みレベル4
凹んだ上に、背景色が変わる。

埋め込みコラム

段落が "[!caption!]" で始まる場合、その段落は指定したキャプションを表題にしたコラム(囲み記事)のように表示されます。記事の本文とは独立した内容や補足などはコラムに入れると良いでしょう。これは段落の一種なので、次に空行が来るまでが一つのコラムになります。

[!徳川家康の遺訓!]
人の一生は重荷を負うて遠き道を行くがごとし。急ぐべからず。
不自由を常と思えば不足なし。こころに望みおこらば困窮したる時を思い出すべし。
堪忍は無事長久の基、いかりは敵と思え。
勝つ事ばかり知りて、負くること知らざれば害その身にいたる。
おのれを責めて人をせむるな。
及ばざるは過ぎたるよりまされり。
☞ 徳川家康の遺訓
×
徳川家康の遺訓
人の一生は重荷を負うて遠き道を行くがごとし。急ぐべからず。
不自由を常と思えば不足なし。こころに望みおこらば困窮したる時を思い出すべし。
堪忍は無事長久の基、いかりは敵と思え。
勝つ事ばかり知りて、負くること知らざれば害その身にいたる。
おのれを責めて人をせむるな。
及ばざるは過ぎたるよりまされり。

埋め込みコラムのキャプションに "~" を前置すると、ページをロードした状態では隠された状態のコラムを設置できます。ネタバレ注意の内容や、クイズのヒントや正解などはこの隠しコラムに書くと良いでしょう。

[!~トーマスエジソンの名言]
非凡な創造力は1%のひらめきと99%の努力により作られる。
失敗したんじゃない。うまくいかない1万の方法を見つけただけだ。
成功の法則などない、挑み続けるだけだ。
全ての可能性を尽くしたと思った時には思い出せ、そうでないことを。

[!~トーマスエジソンの名言]
非凡な創造力は1%のひらめきと99%の努力により作られる。
失敗したんじゃない。うまくいかない1万の方法を見つけただけだ。
成功の法則などない、挑み続けるだけだ。
全ての可能性を尽くしたと思った時には思い出せ、そうでないことを。

罫線

見出しを使わずに記事の内容を区切るには、罫線を使うのが便利です。ハイフン2個だけの行は罫線レベル0で、透明の罫線になります。ハイフン3個からハイフン5個まではレベル1から3の罫線になり、幅と色とマージンが変わります。罫線には画像の回り込みを解除する効果もあります。

罫線レベル0の上。あいうえお。one two three. 一二三。
--
罫線レベル0を二個連続で置く上。かきくけこ。four five six. 四五六。
--
--
罫線レベル1の上。さしすせそ。seven eight nine. 七八九。
---
罫線レベル2の上。たちつてと。ten eleven twelve. 十十一十二。
----
罫線レベル3の上。なにぬねの。thirtheen fourteen fifteen. 十三十四十五。
-----
罫線レベル3の下。はひふへほ。sixteen seventeen eighteen. 十六十七十八。

罫線レベル0の上。あいうえお。one two three. 一二三。


罫線レベル0を二個連続で置く上。かきくけこ。four five six. 四五六。



罫線レベル1の上。さしすせそ。seven eight nine. 七八九。


罫線レベル2の上。たちつてと。ten eleven twelve. 十十一十二。


罫線レベル3の上。なにぬねの。thirtheen fourteen fifteen. 十三十四十五。


罫線レベル3の下。はひふへほ。sixteen seventeen eighteen. 十六十七十八。

記事内の目次

一つの記事が長くなる場合、内容のまとまり毎に適切に小見出しを振った上で、各小見出しに飛ぶための目次を置くと良いでしょう。

* 目次

@page-toc

* 序論

吾輩は猫である。名前はまだない。...

このページの目次は以下のようになります。

サイト横断の目次

サイト内の記事に対する目次を作ることもできます。以下のようにします。並び順を表す "order" オプションには "title"(タイトル)、"date"(日付)、"filename"(ファイル名)を指定します。"reverse" オプションの値が "true" の場合、逆順になります。最大表示件数は "max" オプションで指定します。

例えば、ブログ風に運用する場合に最新記事の一覧を表示したい場合には以下のようにします。

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

普通に前から読んでほしい内容のサイトでは、ファイル名に "001-installation.art" などの連番を振った上で、ファイル名順の目次を置くと良いでしょう。"[order=filename]" オプションはデフォルトなので省略しても良いです。

@site-toc [order=filename]

Wikiのように、順不同でたくさんの記事を集めたサイトの場合、タイトルで目次を作ると良いでしょう。

@site-toc [order=title]

このチュートリアルの目次は以下のようになります。

タグとクロスリファレンス

いくつかの記事で共通する話題のまとまりがある場合、各々の記事にタグをつけて整理すると良いでしょう。"@tags" で始まる行にカンマ区切りでタグを指定することができます(複数形の "tags" です)。タグにつける文字列はカンマを含まなければ何でも良いです。大文字と小文字は区別されます。

@tag サイクリング, ブロンプトン, @神奈川県横浜市

タグをつけた記事の末尾には同一タグの記事に対するクロスリファレンス機能が自動的につきます。表示されたタグをクリックすると、そのタグを含む記事の一覧が表示されます。

記事の中に "@site-tags" という行を置くと、サイト全体のタグの一覧を埋め込むことができます。

@site-tags
チュートリアル (5)
インストールと運用 , 記事の書式 , 画像と動画 , カスタマイズ , ブラウザでファイル管理
インストール (3)
インストールと運用 , カスタマイズ , ブラウザでファイル管理
@鎌倉 (2)
鎌倉の旅 , 鳩サブレー
書式 (2)
記事の書式 , 画像と動画
お土産 (1)
鳩サブレー
旅日記 (1)
鎌倉の旅

一つしか記事を含まないタグはあまり有用ではありません。よって、基本的には同一のタグに該当する記事を二つ以上書いた時点で、タグを置き始めるのが良いでしょう。ただし、地名や人名やバージョン番号などを意味するタグはそれ自体に意味があるので、方針を決めて適宜使っても良いでしょう。"#" や "@" や "$" などを接頭させて何らかの区別をつけるのも良い考えです。

雑多な属性

"@misc" で始まる行で、記事に対する特殊な指示を与えることができます。"noshare"(シェア不可)、"nocomment"(コメント不可)、"notoc"(サイト横断目次から除外)、"nosearch"(全文検索結果から除外)が指定できます。複数指定する場合はカンマ区切りで書きます。

@misc noshare, nocomment, notoc, nosearch

サイトのトップページや目次のページが目次に反映されるのはダサいので、それらの記事には "notoc" 属性をつけておきましょう。"notoc" 属性がある記事は「前へ」「次へ」のリンク構造からも除外されます。

運用中のサイトで新しい記事を執筆する場合、プレビューのためにジェネレータを動かす際にそのファイル名だけを指定して他の記事を更新しないという方法が便利です。その上で、念のために "notoc" を指定しておくと、ファイル名を指定しないでジェネレータを動かした場合に目次やその他のリンクに反映されるのを防ぐことができます。

チュートリアル 書式
comments
----
name:
text: