TartanCloth
A wrapper around the BlueCloth gem which incorporates HTML5 headers, footers, and a table of contents all with a nice stylesheet.
Installation
Add this line to your application's Gemfile:
gem 'tartancloth'
And then execute:
$ bundle
Or install it yourself as:
$ gem install tartancloth
Usage
TartanCloth's main feature is generating a linked Table of Contents
from the headers (h1, h2, h3, h4, h5, h6) in your markdown document.
Simply add a header at any header level (level 2: h2, shown here):
## TOC
TartanCloth will parse the document and collect all headers after the TOC
and create a Table of Contents. The Table of Contents will be inserted at the
location of the ## TOC header, replacing it.
In most of my documents, I include the Title (h1) and a summary before displaying the TOC. I didn't want to include the sections prior to the TOC in the Table of Contents, that's why header collection starts after.
Quick Example
A quick example of using TartanCloth.
Given the following markdown:
markdown.md
# My Wrench User Manual
## Summary
My Wrench is an awesome tool blah, blah blah.
- - -
## TOC
- - -
## Running Wrench from the command line
How to run wrench from the command line
- - -
## Documentation Conventions
Text surrounded with square brackets [] is optional.
Text formatted like `this` indicates a _keyword_.
### Some Other Header
#### Another, Deeper Header
##### Yet Another Header
- - -
## Look at this header
###### Small Note Header
Markit.rb will convert the markdown to HTML, with an embedded stylesheet and include a Table of Contents.
markit.rb
require 'tartancloth'
title = 'My Markdown'
mdsrc = 'path/to/my/markdown.md'
mdout = 'path/to/my/markdown.html'
puts "Title: #{title}"
puts "Source: #{mdsrc}"
puts "Output: #{mdout}"
TartanCloth.new( mdsrc, title ).to_html_file( mdout )
Using TartanCloth from a Rake Task
I like to use TartanCloth from a rake task to generate pretty docs.
markdown.rake
require "pathname"
require 'tartancloth'
# Call this as: rake md2html[path/to/file/to/convert.md]
#
desc "Convert a .MD file to HTML"
task :md2html, [:mdfile] do |t, args|
Rake::Task['markdown:md2html'].invoke( args[:mdfile] )
end
namespace :markdown do
desc "md2html usage instructions"
task :help do
puts <<HELP
----------------------------------------------------------------------
Usage: md2html
Generate HTML from a markdown document
The generated HTML document will be located in the same location as
the source markdown document.
To generate the document, call it as follows:
rake md2html[path/to/doc.md]
Note that no quotes are needed.
To set the title of the document, provide it as an ENV variable:
TITLE="My Title" rake md2html[path/to/doc.md]
If no title is given, the title will default to the filename.
----------------------------------------------------------------------
HELP
end
task :md2html, [:mdfile] do |t, args|
args.with_defaults(:mdfile => nil)
if args[:mdfile].nil?
puts "ERROR: Full path to file to convert required."
puts
puts "usage: rake md2html['path/to/md/file.md']"
exit
end
mdsrc = args[:mdfile]
mdout = mdsrc.pathmap( "%X.html" )
title = ENV['TITLE']
puts "Title: #{title}"
puts "Source: #{mdsrc}"
puts "Output: #{mdout}"
TartanCloth.new( mdsrc, title ).to_html_file( mdout )
end
end # namespace :markdown
A Task to Generate a User Manual
I use the tasks above to generate a user manual as well:
Rakefile
require "bundler/gem_tasks"
desc 'Generate user manual HTML'
task :man do
ENV['TITLE'] = 'User Manual'
Rake::Task['markdown:md2html'].invoke( 'docs/user_manual.md' )
Rake::Task['markdown:md2html'].reenable
end
Available Methods
The TartanCloth object provides the following methods:
###
# Convert a markdown source file to HTML. If a header element with text TOC
# exists within the markdown document, a Table of Contents will be generated
# and inserted at that location.
#
# The TOC will only contain header (h1-h6) elements from the location of the
# TOC header to the end of the document
to_html()
###
# The same as to_html() but writes the HTML to a file.
#
# html_file - path to file
to_html_file( html_file_path )
###
# Build TOC and return body content (including TOC).
# Returned HTML does NOT include doc headers, footer, or stylesheet.
#
# returns HTML that forms the body of the document
body_html()
Credits
- BlueCloth is used to generate the markdown
- Nokogiri is used to generate the table of contents
- Chris Coyier has some great code for pretty HRs
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request