BlueFeather マニュアル

インストール・基本的な使い方

この文書では、BlueFeather そのものの使い方について記述しています。 BlueFeather が解釈する Markdown 記法への独自拡張については、Markdown 記法の拡張を参照してください。

インストール

同梱の setup.rb を実行することにより、ファイルが適切な位置にコピーされ、インストールが完了します。

% ruby setup.rb

もしくは、RubyGems がインストールされていれば、インターネットに接続されたPCから次のように打ち込むことでインストールすることも可能です。

% gem install bluefeather

コマンドラインから使う

基本

インストールが正常に終了していれば、bluefeather コマンドを使って、Markdown記法で書かれたファイルを変換することができます。 インターフェースは以下の通りです。

bluefeather [options] file1 [file2] [file3] ...

たとえば、次のように入力することで、拡張子が .bftext のファイル全てをhtmlファイルに変換することができます。

% bluefeather *.bftext
example1.bftext => example1.html (4240 byte)
example2.bftext => example2.html (5613 byte)
example3.bftext => example3.html (10499 byte)
%

強制変換オプション（--force）

通常 bluefeather コマンドは、入力テキストファイルが更新されていたときのみ（更新日時が新しくなっていたときのみ）変換を行います。

% bluefeather example1.bftext
example1.bftext => example1.html (4240 byte)
% bluefeather example1.bftext
%

更新日時に関わらず全てのファイルを変換したい場合には、--force オプションをつけて実行してください。

% bluefeather example1.bftext
example1.bftext => example1.html (4240 byte)
% bluefeather --force example1.bftext
example1.bftext => example1.html (4240 byte)
%

この他のオプションの種類については、この文書内のコマンドラインオプションの項を参照してください。

拡張子による出力htmlの違い

bluefeather コマンドでは、変換対象のファイルの拡張子によって、どのようなhtmlファイルを出力するかが異なります。

.md, .bfdoc
DTD宣言やhead要素などを含んだ、完全なHTML文書を生成する
それ以外
HTML片を生成する（DTD宣言やhead要素は含まない）

たとえば、次のような一文だけが書かれたテキストファイルがあるとします。

test paragraph.

このテキストファイルが test1.bftext という名前であれば、変換結果（test1.html）はこのようになります。

<p>test paragraph.</p>

しかし、もしこのファイルが test1.bfdoc という名前であれば、上記の例と異なり完全なHTML文書を生成します。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>no title (Generated by BlueFeather)</title>
</head>
<body>

<p>test paragraph.</p>

</body>
</html>

なお、このとき変換する文書にレベル1の見出しが含まれていれば、その見出しが自動的にhtml文書のtitleとして使われます。

test2.bfdoc
Test Document
=============

test paragraph.
test2.html（出力結果）
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Test Document</title>
</head>
<body>

<h1 id="bfheader-a5decd745d43af4aa8cf62eef5be43ac">Test Document</h1>

<p>test paragraph.</p>

</body>
</html>

文書メタデータ

拡張子が .bfdoc や .md のファイルには、文書メタデータを付け加えることが出来ます。

test3.bfdoc
Title: Test Document
CSS: style.css

Test paragraph.
test3.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Test Document</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>

<p>Test paragraph.</p>

</body>
</html>

メタデータについての詳細は、メタデータリファレンスを参照してください。

標準入力からの読み込み（stdin-mode）

ファイル名を - とだけ指定すると特殊な動作モードになり、標準入力からテキストを読み込み、変換結果のhtmlを標準出力へ書き込みます。 パイプラインを用いるときなどに便利です。

% bluefeather -

コマンドラインオプション

-e NAME, --encoding NAME
変換するテキストファイルのエンコーディングを、指定したエンコーディングとして解釈します。 （shift-jis / euc-jp / utf-8 / ascii のうちいずれか、もしくは最初の数文字。標準では utf-8）
-f TYPE, --format TYPE
出力するhtmlの種別を特定します。 text, bftext ならhtml片を、 document, bfdoc なら完全なhtml文書を出力します。 （標準ではファイルの拡張子から自動判別）
--force
入力ファイルの更新日時に関わらず、全てのファイルを変換します。（標準では入力ファイルが新しくなっている場合のみ変換）
-h, --help
bluefeather コマンドの解説を表示します。
-o DIR, --output DIR
指定したディレクトリに全てのファイルを生成します。（標準ではパース対象のファイルと同じ位置に生成）
-q, --quiet
動作時に作業の状況や結果を表示しません。
--suffix .SUF
出力するファイルの拡張子を指定します。（標準は.html）
-v, --verbose
冗長フラグ。作業内容を詳細に表示します。
--version
BlueFeather のバージョンを表示します。

Rubyスクリプト内で使う

基本

もっとも基本的なメソッドは、BlueFeather.parse です。 このメソッドにより、BlueFeatherを用いて文字列をパースし、htmlに変換することができます。

require 'bluefeather'

str = "もっとも基本的な例です。"
puts BlueFeather.parse(str)      #=> "<p>もっとも基本的な例です。</p>"

また、BlueFeather.parse_file を使えば、ファイルの中にある文字列を読み込んでパースすることができます。

BlueFeather.parse_file('test1.txt')
BlueFeather.parse_file('test2.markdown')
BlueFeather.parse_file('test3.bftext')

HTML文書の生成

parse や parse_file メソッドの代わりに、parse_document や parse_document_file メソッドを用いることによって、HTML片ではなく完全なHTML文書を生成することが可能です。

test.bfdoc
The sentence is expected as HTML.
test.rb
require 'bluefeather'

puts '-- parse_file --'
puts BlueFeather.parse_file('test.bfdoc')

puts '-- parse_document_file --'
puts BlueFeather.parse_document_file('test.bfdoc')
実行結果
-- parse_file --
<p>The sentence is expected as HTML.</p>

-- parse_document_file --
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>no title (Generated by BlueFeather)</title>
</head>
<body>

<p>The sentence is expected as HTML.</p>

</body>
</html>

文書のメタデータ取得

文書をパースして直接 html を生成するのではなく、BlueFeather::Document オブジェクトを生成することにより、その文書のメタデータを取得することができます。

doc = BlueFeather::Document.parse(<<EOS)
Title: test document
CSS: style.css

test paragraph.
EOS

p doc['title']     # => "test document"
p doc['css']       # => "style.css"
p doc[:css]        # => "style.css"
p doc['undefined'] # => nil

p doc.body         # => "test paragraph."

この BlueFeather::Document オブジェクトから実際に html を生成するには、 to_html メソッドを呼んでください。

doc.to_html