Installing and Basic Usage - BlueFeather Manual

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
- Use by Command-line
  - Basic
  - Option for Forcing to Convert (`--force`)
  - Extname Switch
  - Document Metadata
  - stdin-mode
  - Command-line Options
- Use in Ruby Script
  - Basic
  - Generate HTML Document
  - Get document metadata

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