Title: Installing and Basic Usage - BlueFeather Manual
CSS: black.css

<div class="back"><a href="index.html">BlueFeather Manual</a></div>



Installing and Basic Usage
====

 This document describes only usage of the software. If you want to know about
syntax, see [Markdown Syntax Extension](format-extension.html).

{toc}


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](#commandline-options).


### 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](metadata-reference.html).

### stdin-mode

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

	% bluefeather -


### Command-line Options {#commandline-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