tartancloth 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tartancloth.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Jeff McAffee
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,200 @@
+# 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 that it generates 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
+
+- - -
+## Credits
+
++   [BlueCloth](https://github.com/ged/bluecloth) is used to generate the markdown
++   [Nokogiri](http://nokogiri.org/) is used to generate the table of contents
++   Chris Coyier has some [great code for pretty HRs](http://css-tricks.com/examples/hrs/)
+
+- - -
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/tartancloth.rb

@@ -0,0 +1,335 @@
+require 'bluecloth'
+require 'nokogiri'
+
+
+
+class TartanCloth
+
+  VERSION = "0.0.1"
+
+  attr_accessor :title
+
+  def initialize( markdown_file, title = nil )
+    @markdown_file = markdown_file
+    @title = title
+  end
+
+  def to_html_file( html_file )
+
+    File.open( html_file, 'w') do |f|
+      f << to_html()
+    end
+  end
+
+  ###
+  # 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
+  def to_html
+    bc = BlueCloth::new( File::read( @markdown_file ), header_labels: true )
+    content = bc.to_html
+
+    content = build_toc( content )
+
+    html = ""
+
+    # Add a well formed HTML5 header.
+    html << html_header(title)
+
+    # Add the body content.
+    html << content
+
+    # Add the document closing tags.
+    html << html_footer()
+  end
+
+  ###
+  # Build a TOC based on headers located within HTML content.
+  # 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
+  def build_toc( html_content )
+    # Generate Nokogiri elements from HTML
+    doc = Nokogiri::HTML::DocumentFragment.parse( html_content )
+
+    # Find the TOC header
+    toc = find_toc_header(doc)
+
+    # Just return what was passed to us if there's no TOC.
+    return html_content if toc.nil?
+
+    # Get all headers in the document, starting from the TOC header.
+    headers = get_headers(doc, toc)
+
+    # Build the link info for the TOC.
+    toc_links = []
+    headers.each do |element|
+      toc_links << link_hash(element)
+    end
+
+    # Convert link info to markdown.
+    toc_md = toc_to_markdown(toc_links)
+
+    # Convert the TOC markdown to HTML
+    bc = BlueCloth::new( toc_md, pseudoprotocols: true )
+    toc_content = bc.to_html
+
+    # Convert the TOC HTML to Nokogiri elements.
+    toc_html = Nokogiri::HTML::DocumentFragment.parse(toc_content)
+
+    # Add toc class to the <ul> element
+    toc_html.css('ul').add_class('toc')
+
+    # Insert the TOC content before the toc element
+    toc.before(toc_html.children)
+
+    # Remove the TOC header placeholder element.
+    toc.remove
+
+    # Return the HTML
+    doc.to_html
+  end
+
+  ###
+  # Convert an array of link hashes to markdown
+  #
+  # toc_links - hash of links
+  # returns - markdown content
+  def toc_to_markdown(toc_links)
+    markdown = "## Table of Contents\n\n"
+    toc_links.each do |link_data|
+      text = link_data[:text]
+      link = link_data[:link]
+      klass = link_data[:klass]
+      markdown << "+ [[#{text}](##{link})](class:#{klass})\n"
+    end
+    markdown << "\n"
+  end
+
+  ###
+  # return the TOC header element or nil
+  #
+  # doc - Nokogiri DocumentFragment
+  def find_toc_header(doc)
+    return nil unless doc
+
+    doc.children.each do |element|
+      return element if is_toc_header(element)
+    end
+
+    return nil
+  end
+
+  ###
+  # returns true if the element is a header (h1-h6) element
+  def is_header_element(element)
+    %w(h1 h2 h3 h4 h5 h6).include? element.name
+  end
+
+  ###
+  # returns true when a header (h1-h6) element contains the text: TOC
+  def is_toc_header(element)
+    return (is_header_element(element) && element.text == 'TOC')
+  end
+
+  ###
+  # Create an array of all header (h1-h6) elements in an HTML document
+  # starting from a specific element
+  #
+  # starting_element - element to start parsing from
+  # returns - array of Nokogiri elements
+  def get_headers(doc, starting_element)
+    headers = []
+    capture = false
+
+    doc.children.each do |element|
+      unless capture
+        capture = true if element == starting_element
+        next
+      end # unless
+
+      headers << element if is_header_element(element)
+    end
+
+    headers
+  end
+
+  ###
+  # Build a link hash for an element containing the text, link,
+  # and a children array.
+  #
+  # element - Nokogiri element
+  def link_hash(element)
+    # The previous element should be a simple anchor.
+    # Get the actual link value from the anchor.
+    a = element.previous_element
+    anchor_link = a.attributes['name'].value if a.name == 'a'
+
+    # Store the header text (link text) and the anchor link and a class for styling.
+    { text: element.text, link: anchor_link, klass: "#{element.name}toc" }
+  end
+
+  # Create an HTML5 header
+  #
+  # returns - HTML header and body open tags
+  def html_header(title)
+    styles = css()
+    header = <<HTML_HEADER
+<!DOCTYPE html>
+<html>
+  <head><title>#{title}</title></head>
+
+  #{styles}
+
+  <body>
+    <div class="content">
+      <div class="rendered-content">
+
+HTML_HEADER
+  end
+
+  ###
+  # Create some stylish CSS
+  #
+  # returns - html style element
+  def css()
+    styles = <<CSS
+<style media="screen" type="text/css">
+<!--
+  body {
+    font-family: Arial, sans-serif;
+  }
+
+  .content {
+    margin: 0 auto;
+    min-height: 100%;
+    padding: 0 0 100px;
+    width: 980px;
+    border: 1px solid #ccc;
+    border-radius: 5px;
+  }
+
+  .rendered-content {
+    padding: 10px;
+  }
+
+  /* Fancy HR styles based on http://css-tricks.com/examples/hrs/ */
+  hr {
+    border: 0;
+    height: 1px;
+    background-image: -webkit-linear-gradient(left, rgba(200,200,200,1), rgba(200,200,200,0.5), rgba(200,200,200,0));
+    background-image:    -moz-linear-gradient(left, rgba(200,200,200,1), rgba(200,200,200,0.5), rgba(200,200,200,0));
+    background-image:     -ms-linear-gradient(left, rgba(200,200,200,1), rgba(200,200,200,0.5), rgba(200,200,200,0));
+    background-image:      -o-linear-gradient(left, rgba(200,200,200,1), rgba(200,200,200,0.5), rgba(200,200,200,0));
+  }
+
+  h1 {
+    font-size: 24px;
+    font-weight: normal;
+    line-height: 1.25;
+  }
+
+  h2 {
+    font-size: 20px;
+    font-weight: normal;
+    line-height: 1.5;
+  }
+
+  h3 {
+    font-size: 16px;
+    font-weight: bold;
+    line-height: 1.5625;
+  }
+
+  h4 {
+    font-size: 14px;
+    font-weight: bold;
+    line-height: 1.5;
+  }
+
+  h5 {
+    font-size: 12px;
+    font-weight: bold;
+    line-height: 1.66;
+    text-transform: uppercase;
+  }
+
+  h6 {
+    font-size: 12px;
+    font-style: italic;
+    font-weight: bold;
+    line-height: 1.66;
+    text-transform: uppercase;
+  }
+
+  pre  {
+    margin-left: 2em;
+    display: block;
+    background: #f5f5f5;
+    font-family: monospace;
+    border: 1px solid #ccc;
+    border-radius: 2px;
+    padding: 1px 3px;
+  }
+
+  code {
+    background: #f5f5f5;
+    font-family: monospace;
+    border: 1px solid #ccc;
+    border-radius: 2px;
+    padding: 1px 3px;
+  }
+
+  pre, code {
+    font-size: 12px;
+    line-height: 1.4;
+  }
+
+  pre code {
+    border: 0;
+    padding: 0;
+  }
+
+  ul.toc li {
+    list-style: none;
+    font-size: 14px;
+  }
+
+  ul.toc li span.h3toc {
+    margin-left: 20px;
+  }
+
+  ul.toc li span.h4toc {
+    margin-left: 40px;
+  }
+
+  ul.toc li span.h5toc {
+    margin-left: 60px;
+  }
+
+  ul.toc li span.h6toc {
+    margin-left: 80px;
+  }
+-->
+</style>
+CSS
+  end
+
+  ###
+  # returns - HTML closing tags
+  def html_footer()
+    footer = <<HTML_FOOTER
+
+      </div> <!-- .content -->
+    </div> <!-- .rendered-content -->
+  </body>
+</html>
+HTML_FOOTER
+  end
+
+end

data/tartancloth.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'tartancloth'
+
+Gem::Specification.new do |spec|
+  spec.name          = "tartancloth"
+  spec.version       = TartanCloth::VERSION
+  spec.authors       = ["Jeff McAffee"]
+  spec.email         = ["jeff@ktechsystems.com"]
+  spec.description   = %q{A wrapper around the BlueCloth gem which incorporates HTML5 headers, footers, and a table of contents all with a nice stylesheet.}
+  spec.summary       = %q{Generate nice HTML with a table of contents}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+
+  spec.add_runtime_dependency 'bluecloth', '~> 2.2', '>= 2.2.0'
+  spec.add_runtime_dependency 'nokogiri', '~> 1.5', '>= 1.5.6'
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: tartancloth
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Jeff McAffee
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bluecloth
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.5.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.5.6
+description: A wrapper around the BlueCloth gem which incorporates HTML5 headers,
+  footers, and a table of contents all with a nice stylesheet.
+email:
+- jeff@ktechsystems.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/tartancloth.rb
+- tartancloth.gemspec
+homepage: ''
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Generate nice HTML with a table of contents
+test_files: []
+has_rdoc: