BlueFeather Manual

Installing and Basic Usage

This document describes only usage of the software. If you want to know about syntax, see Markdown Syntax Extension.

Install

Run setup.rb. Then required files will be copied and installing will be complete.

% ruby setup.rb

Or use RubyGems.

% gem install bluefeather

Use by Command-line

Basic

If installing is correctly completed, you can use bluefeather command. This command convert Markdown text to html.

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

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

Option for Forcing to Convert (--force)

In default, bluefeather command converts only input files that were modified.

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

If you want to convert all files despite modified time of them, use --force option.

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

If you know better about other options, see the section of Command-line Option.

Extname Switch

bluefeather command switches by extname of an input file how generate a html file.

.md, .bfdoc
generate html document
others
generate html part

For example, see the text.

test paragraph.

If this text is named 'test1.bftext', bluefeather generates test1.html such as this.

<p>test paragraph.</p>

But this text is named 'test1.bfdoc', generated html is changed.

<!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>

If the converted document is include h1 element, BlueFeather use it's content for title of html document.

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

test paragraph.
test2.html (output)
<!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>

Document Metadata

You can add document metadata to files which have extname .bfdoc or .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>

If you know better about metadata, see the section of Metadata Reference.

stdin-mode

If you use stdin and stdout, specify a parameter only -. This mode is useful for pipe-line.

% bluefeather -

Command-line Options

% bluefeather --help
bluefeather - Extended Markdown Converter

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

Options:
  -e, --encoding NAME   parse input files as encoding of NAME.
                        (s[hift-jis] / e[uc-jp] / u[tf-8] / a[scii]
                         default: 'utf-8')
  -f, --format TYPE     specify format.
                        (t[ext]      => text mode
                         d[ocument]  => document mode)
      --force           write even if target files have not changed.
                        (default: only if target files have changed)
  -h, --help            show this help.
  -o, --output DIR      output files to DIR. (default: same as input file)
  -q, --quiet           no output to stderr.
      --suffix .SUF     specify suffix of output files. (default: '.html')
  -v, --verbose         verbose mode - output detail of operation.
      --version         show BlueFeather version.

Advanced Usage:
  * If specify files only '-', bluefeather read from stdin and write to stdout.


Example:
  bluefeather *.bftext *.bfdoc
  bluefeather -v --sufix .xhtml -o ../ sample.markdown
  bluefeather -

More info:
  see <http://ruby.morphball.net/bluefeather/>
%

Use in Ruby Script

Basic

Most basic method is BlueFeather.parse.

require 'bluefeather'

str = "most basic example."
puts BlueFeather.parse(str)      #=> "<p>most basic example.</p>"

And you can use BlueFeather.parse_file.

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

Generate HTML Document

If you want a html document not html fragment, you may use parse_document or parse_document_file.

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')
Result
-- 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>

Get document metadata

If you want to get directly metadata of document, instead of BlueFeather module method, you should use BlueFeather::Document class.

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."

to_html parses the text and generates an html document actually.

doc.to_html