README.md in mdoc-0.0.3 vs README.md in mdoc-0.0.5
- old
+ new
@@ -1,47 +1,134 @@
-
-MDOC: markdown document converting/management tool
-=======================================================
-
-Requirement
-----------------
-
-- Ruby 1.9.x
-- pandoc in path for docx/rtf conversion
-- xelatex in path for pdf conversion
-
-Command line options
--------------------------
-
-Convert a markdown file (`readme.md`) to docx (`readme.docx`):
-
- mdoc -t docx readme.md
-
-Use `mdoc --help` for more options.
-
-Online Preview
------------------
-
-Put a markdown document to an temporary url for revew:
-
- mdoc --preview readme.md
-
-This will open your browser to show a converted document (use documentup).
-
-Meta information in header
------------------------------
-
-Three different formats are supported:
-
-1. pandoc like three line header:
-
- % title
- % author
- % date
-
-2. multi-header (separate by first blank line)
-
- Title: some key
- Author: some key
-
-3. separator:
- if `% ---` is the first no-blank line, the contents between until the next `% ---` will be treated as header.
+# Mdoc-gem
+
+A tool for convert document between several different formats.
+
+Mdoc has a modularized structure, easily extensible with custom processors.
+
+## Install
+
+ gem install mdoc
+
+(requires ruby 1.9.x)
+
+## Synopsis
+
+- Convert a markdown file (`readme.md` in this example) to html (use `default.html` template):
+
+ mdoc readme.md
+
+This will create a `readme.html` file besides `readme.md`.
+
+- Convert a markdown file with a custom template:
+
+ mdoc -t custom.html readme.md
+
+Mdoc will try to find `custom.html.erb` from `./templates` folder, or you can specify it by:
+
+ mdoc -t custom.html -d ~/mdoc_templates readme.md
+
+- Specify output filename:
+
+ mdoc -o README.html readme.md
+
+Or print out to STDOUT:
+
+ mdoc -O readme.md
+
+## Markdown with Meta Information
+
+The default source file format is markdown[^1]. Mdoc convert it into a document class
+`Mdoc::Document::Kramdown`, with supports all extensions from Kramdown[^2].
+
+[^1]: Wikipedia: http://en.wikipedia.org/wiki/Markdown
+[^2]: Kramdown Syntax: http://kramdown.rubyforge.org/quickref.html
+
+Additionally, you can put meta informations in the begin of your source file, in two
+different format:
+
+1. pandoc like three line header (max 3 lines)
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ % title
+ % author
+ % date
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+2. multi-header (first non-blank line with three or more dashes)
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ % ---
+ title: some key
+ author: some key
+ % ---
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The heading `%` is optional.
+
+You can access those information from erb files by `<%= meta.title %>`
+
+## Processors
+
+The following processors are enabled by default:
+
+- `add_toc`: Add `table of contents` field in the contents body;
+- `add_title`: Add a `meta.title` as a first level header in the contents body;
+- `smart_code_block`: delete extra heading/trailing blank lines in code blocks;
+
+You can disable some of the processors by:
+
+ mdoc -z add_toc,smart_code_block readme.md
+
+## Use Mdoc as a Library
+
+~~~~~~~~~~~~~~~~~~~~~~~~~ ruby
+
+ require 'mdoc'
+ module Mdoc
+ class Processor
+ class Custom < Processor
+ def process!(document)
+ document.meta.title += ' (draft)' # edit the document title
+ document.body.gsub!(/https/, 'http') # change the source body text
+ end
+
+ def repeatable?
+ true # default is false
+ end
+ end
+
+ class Other < Processor
+ def process!(document)
+ # do some thing ...
+ end
+ end
+ end
+
+ class Writer
+ class CustomWriter
+ def process!(document)
+ # fh.puts ...
+ end
+ end
+ end
+ end
+
+ Mdoc.convert!('somefile.md') do |pipeline|
+ pipeline.insert :custom # insert into the begin of the processor pipeline
+ pipeline.insert :other, :before => :custom # or :after => :some_processor
+ pipeline.remove :todo
+
+ pipeline.writer = CustomWriter
+ end
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unless you define a method `repeatable?` and returns `true`, one processor will
+process a document at most once.
+
+## Tests
+
+ rubocop && rspec