brief 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4ea25b279da5166d726a9463be10836ab9b6d7bb
-  data.tar.gz: e52d0270a01c924196c8ab59250df0973320589d
+  metadata.gz: f22a8f02957425fed25d8adfa60cd4b9aa2ced77
+  data.tar.gz: 5c6e4bbb9a213eeaeac820cef681f17fc308d08a
 SHA512:
-  metadata.gz: 250b23f611f467ec9731114557f84d8bf24e498642849eab59dcb79f7a7c1790ea33b8f734a3017f515ad025caf5353625b0ec972c7e016eb7682eafe9aa063a
-  data.tar.gz: 88a4250edb54523fdb51f18700a149831a5835d031cf67fbc49c142bb6d3abeccec9eff48c32df99f9ded979330c9223b7f7934819b87e4f79f33a67292b2e3e
+  metadata.gz: 86ceea62469f2a210e595a03b056cda6297b0adbce06c90659f664b284e9d61a3b1f9be7d125ee759632bd08c8e585f2c8e3fdca74559f92675c9d56b486b067
+  data.tar.gz: 0f5fd7ccea4cd89b9243b6409297bc99525c37c2a6c5baca0f0b7aceb65f6ef067d042055f8e7915d28306c2c796f3307a35a4797c72593efedc63244af51c2c

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+### 1.1.0 
+
+- Introducing Briefcases
+
+  Briefcases are top level folders which contain model definition code
+  and configuration, and a hierarchy of subfolders each containing
+  markdown documents which will map to models.
+
+- Model Definition DSL
+
+  Briefcases can have more than one model class.  These models can have
+  attributes, and can specify structure rules which allow for the
+  document to be parsed in a semantic way.
+
+### 1.2.0
+
+- Introducing Document Sections 
+  - Added `define_section` to the model definition DSL. This will allow certain headings to be used to access a 
+    section of the document in isolation. 
+    
+    Document sections have their own mini-structure, and will 
+    contain at least one, usually more than one repeatable pattern.
+
+    These repeatable patterns will usually contain short-hand
+    references to other documents, or key attributes that can be used to
+    create other documents.
+
+    Document sections are how one document can be broken apart into many
+    other documents.
+
+- CLI Actions
+  - Added `actions` to the method definition DSL. This will allow a model instance to define a method, and
+    then dispatch calls to this method from the Brief CLI interface.
+
+- Changed HTML rendering
+  - using a custom redcarpet markdown renderer in order to include
+    data-attributes on heading tags
+  - rendered html retains line number reference to the source markdown

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brief (1.0.0)
+    brief (1.2.0)
       activemodel
       activesupport
       commander
@@ -39,7 +39,7 @@ GEM
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.2.5)
     equalizer (0.0.9)
-    faraday (0.9.0)
+    faraday (0.9.1)
       multipart-post (>= 1.2, < 3)
     github-fs (0.0.1)
       activesupport (> 3.2.0)
@@ -50,10 +50,10 @@ GEM
     i18n (0.7.0)
     ice_nine (0.11.1)
     inflecto (0.0.2)
-    json (1.8.1)
+    json (1.8.2)
     method_source (0.8.2)
     mini_portile (0.6.2)
-    minitest (5.5.0)
+    minitest (5.5.1)
     multipart-post (2.0.0)
     nokogiri (1.6.5)
       mini_portile (~> 0.6.0)
@@ -67,7 +67,7 @@ GEM
       pry (>= 0.9.10, < 0.11.0)
     rack (1.6.0)
     rake (10.4.2)
-    redcarpet (3.2.0)
+    redcarpet (3.2.2)
     rspec (3.1.0)
       rspec-core (~> 3.1.0)
       rspec-expectations (~> 3.1.0)
@@ -87,7 +87,7 @@ GEM
     thread_safe (0.3.4)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
-    virtus (1.0.3)
+    virtus (1.0.4)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
       descendants_tracker (~> 0.0, >= 0.0.3)

data/README.md

@@ -103,9 +103,18 @@ define "Post" do
 end
 ```
 
-you can either call that method as you normally would, or you can run 
-that action from the command line:
+you can either call that method as you normally would: 
+
+```ruby
+post = Brief.case.posts.where(:status => "draft")
+post.publish()
+```
+
+or you can run that action from the command line:
 
 ```bash
 brief publish posts ./posts/*.html.md
 ```
+
+this will find all of the post models matching the document, and then
+call the publish method on them.

data/lib/brief/adapters/middleman.rb

@@ -0,0 +1,18 @@
+module Brief::Adapters
+  class MiddlemanExtension
+
+    def self.activate_brief_extension
+      ::Middleman::Extensions.register(:brief, Brief::Adapters::MiddlemanExtension)
+    end
+
+    def initialize(app, options_hash={}, &block)
+      super
+
+      app.include(ClassMethods)
+
+      options_hash.each do |key,value|
+        app.set(key, value)
+      end
+    end
+  end
+end

data/lib/brief/briefcase.rb

@@ -60,7 +60,15 @@ module Brief
     end
 
     def models_path
-      root.join options.fetch(:models_path) { config.models_path }
+      value = options.fetch(:models_path) { config.models_path }
+
+      if value.to_s.match(/\./)
+        Pathname(Dir.pwd).join(value)
+      elsif value.to_s.match(/\//)
+        Pathname(value)
+      else
+        root.join(value)
+      end
     end
 
     def repository

data/lib/brief/document/content_extractor.rb

@@ -25,7 +25,13 @@ module Brief
       if settings = attribute_set.fetch(meth, nil)
         if settings.args.length == 1 && settings.args.first.is_a?(String)
           selector = settings.args.first
-          document.css(selector).try(:text)
+          matches = document.css(selector)
+
+          if matches.length > 1
+            selector.match(/first-of-type/) ? matches.first.text : matches.map(&:text)
+          else
+            matches.first.try(:text)
+          end
         end
       end
     end

data/lib/brief/document/front_matter.rb

@@ -7,11 +7,17 @@ module Brief
         @frontmatter || load_frontmatter
       end
 
+      def frontmatter_line_count
+        (@raw_frontmatter && @raw_frontmatter.lines.count) || 0
+      end
+
       protected
 
       def load_frontmatter
-        if content =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
-          self.content = content[($1.size + $2.size)..-1]
+        if raw_content =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
+          self.content = raw_content[($1.size + $2.size)..-1]
+          @frontmatter_line_count = $1.lines.size
+          @raw_frontmatter = $1
           @frontmatter = YAML.load($1).to_mash
         end
       end

data/lib/brief/document/rendering.rb

@@ -3,26 +3,23 @@ module Brief
     module Rendering
       extend ActiveSupport::Concern
 
-      def to_html
-        self.class.renderer.render(content)
-      end
-
-      def css(*args, &block)
-        parser.send(:css, *args, &block)
-      end
-
-      def at(*args, &block)
-        parser.send(:at, *args, &block)
-      end
-
-      def parser
-        @parser ||= Nokogiri::HTML.fragment(to_html)
+      # Uses a custom Redcarpet::Render::HTML subclass
+      # which simply inserts data attributes on each heading element
+      # so that they can be queried with CSS more deliberately.
+      class HeadingWrapper < ::Redcarpet::Render::HTML
+        def header(text, level)
+          "<h#{level} data-level='#{level}' data-heading='#{ text }'>#{text}</h#{level}>"
+        end
       end
 
       module ClassMethods
+        def renderer_class
+          HeadingWrapper
+        end
+
         def renderer
           @renderer ||= begin
-                          r = ::Redcarpet::Render::HTML.new(:tables => true,
+                          r = renderer_class.new(:tables => true,
                                             :autolink => true,
                                             :gh_blockcode => true,
                                             :fenced_code_blocks => true,
@@ -32,6 +29,39 @@ module Brief
                         end
         end
       end
+
+      # Documents can be rendered into HTML.
+      #
+      # They will first be put through a Nokogiri processor pipeline
+      # which allows us to wrap things in section containers, apply data
+      # attributes, and other things to the HTML so that the output HTML retains its
+      # relationship to the underlying data and document structure.
+      def to_html(options={})
+        if options[:wrap] == false
+          unwrapped_html
+        else
+          wrapper = options.fetch(:wrapper, 'div')
+          "<#{ wrapper } data-brief-model='#{ model_class.type_alias }' data-brief-path='#{ relative_path_identifier }'>#{ unwrapped_html }</#{wrapper}>"
+        end
+      end
+
+      def unwrapped_html
+        parser.to_html
+      end
+
+      protected
+
+      def to_raw_html
+        renderer.render(content)
+      end
+
+      def renderer
+        @renderer ||= self.class.renderer
+      end
+
+      def renderer=(value)
+        @renderer = value
+      end
     end
   end
 end

data/lib/brief/document/section/builder.rb

@@ -0,0 +1,89 @@
+class Brief::Document::Section
+  class Builder
+    def self.run(source, options={})
+      new(source, options).to_fragment
+    end
+
+    attr_accessor :source, :nodes, :low, :high
+
+    def initialize(source, options={})
+      @source = source.map do |item|
+        level, group = item
+        [level, group.map {|f| f.is_a?(String) ? Nokogiri::HTML.fragment(f) : f }]
+      end
+
+      @low = options.fetch(:low, 1)
+      @high = options.fetch(:high, 6)
+      @nodes = []
+      @cycles = 0
+
+      run
+    end
+
+    def run
+      source.length.times do
+        source.each_with_index do |item, index|
+          n = index + 1
+          level, fragments = item
+          next_level, next_fragments = source[n]
+
+          if next_level && (next_level == level) && (level > low)
+            new_fragment = (fragments + next_fragments).map(&:to_html).join("")
+            source[index] = [level, [Nokogiri::HTML.fragment(new_fragment)]]
+            source[n] = nil
+          end
+        end
+
+        source.compact!
+      end
+
+      until even? || maxed_out?
+        source.map! do |item|
+          level, fragments = item
+          [level, fragments.first]
+        end
+
+        source.each_with_index do |item, index|
+          level, fragment = item
+          n = index + 1
+          next_level, next_fragment = source[n]
+
+          if fragment && next_level && (next_level > level)
+            parent = fragment.css("section, article").first
+            parent.add_child(next_fragment)
+            source[index] = [level, fragment]
+            source[n] = nil
+          end
+        end
+
+        source.compact!
+
+        @cycles += 1
+      end
+
+      self.nodes = source.map(&:last)
+
+      self.nodes.each do |node|
+        parent = node.css("section, article").first
+        if %w(h1 h2 h3 h4 h5 h6).include?(parent.children.first.name)
+          parent['data-heading'] = parent.children.first.text
+        end
+      end
+
+      self.nodes.map!(&:to_html)
+    end
+
+    def maxed_out?
+      @cycles > source.length
+    end
+
+    def even?
+      source.map(&:first).uniq.length == 1
+    end
+
+    def to_fragment
+      @html = nodes.join("") unless nodes.empty?
+      Nokogiri::HTML.fragment(@html || "<div/>")
+    end
+  end
+end

data/lib/brief/document/section/mapping.rb

@@ -0,0 +1,61 @@
+class Brief::Document::Section
+  class Mapping
+    def initialize(title, options={})
+      @title = title
+      @options = options
+      @config  = {}.to_mash
+    end
+
+    def selectors
+      selector_config.keys
+    end
+
+    def selector_config
+      config.selectors
+    end
+
+    def config
+      @config
+    end
+
+    def options
+      @options
+    end
+
+    def title
+      @title
+    end
+
+    def selector
+      @selector || :next
+    end
+
+    def each(*args, &block)
+      @selector = args.first
+      self
+    end
+
+    def heading(*args, &block)
+      send(:each, *args, &block)
+    end
+
+    def has(*args)
+      options = args.extract_options!
+
+      unless options.empty?
+        config.selectors ||= {}
+        config.selectors.merge!(selector => options)
+      end
+
+      self
+    end
+
+    def is_a(*args)
+      options = args.extract_options!
+      klass = args.first
+      options[:is_a] = klass if klass
+
+      self
+    end
+  end
+end

data/lib/brief/document/section.rb

@@ -0,0 +1,41 @@
+class Brief::Document::Section
+  attr_accessor :title, :fragment
+  attr_reader :config
+
+  Headings = %w(h1 h2 h3 h4 h5 h6)
+
+  def initialize(title, fragment, config)
+    @title = title
+    @fragment = fragment
+    @config = config
+  end
+
+  def items
+    return @items if @items
+
+    data = []
+
+    config.selectors.each do |selector|
+      settings = config.selector_config[selector]
+
+      if Headings.include?(selector)
+        headings = fragment.css("article > h2")
+        articles = headings.map(&:parent)
+
+        if !settings.empty?
+          articles.compact.each do |article|
+            data.push(settings.inject({}.to_mash) do |memo, pair|
+              attribute, selector = pair
+              result = article.css(selector)
+              memo[attribute] = result.length > 1 ? result.map(&:text) : result.text
+              memo
+            end)
+          end
+        end
+      end
+    end
+
+    @items = data
+  end
+end
+

data/lib/brief/document/structure.rb

@@ -0,0 +1,146 @@
+module Brief
+  class Document::Structure
+    attr_accessor :fragment, :content_lines
+
+    def initialize(fragment,content_lines=[])
+      @fragment = fragment
+      @content_lines = content_lines
+    end
+
+    def prescan
+      content_lines.each_with_index do |line, index|
+        if line.match(/^#/)
+          line = line.strip
+          level = line.count('#')
+          text = line.gsub('#','').strip
+
+          if level > 0 && text.length > 0
+            line_number = index + 1
+            heading = find_heading_by(level, text)
+
+            if heading
+              heading.element.set_attribute('data-line-number', line_number)
+            end
+          end
+        end
+      end
+    end
+
+    def create_wrappers
+      return if @elements_have_been_wrapped
+
+      elements      = fragment.children
+
+      mapping = []
+      bucket = []
+
+      current_level = Util.level(elements.first)
+
+      elements.each_cons(2) do |element, next_element|
+        bucket << element
+
+        if Util.is_header?(next_element) && Util.level(next_element) >= current_level
+          mapping.push([current_level, bucket])
+          bucket = []
+        end
+
+        if Util.is_header?(element)
+          current_level = Util.level(element)
+        end
+      end
+
+      mapping.push([current_level, bucket]) unless mapping.include?(bucket)
+
+      base_fragment = Nokogiri::HTML.fragment("<div class='brief top level' />")
+
+      mapping.map! do |item|
+        level, group = item
+        group.reject! {|i| i.text == "\n" }
+
+        if level == 0
+          base_fragment = fragment = Nokogiri::HTML.fragment("<div class='brief top level'>#{ group.map(&:to_html).join("") }</div>")
+        elsif level <= lowest_level
+          fragment = Nokogiri::HTML.fragment("<section>#{ group.map(&:to_html).join("") }</section>")
+        elsif level > lowest_level
+          # should be able to look at the document section mappings and
+          # apply custom css classes to these based on the name of the section
+          fragment = Nokogiri::HTML.fragment("<article>#{ group.map(&:to_html).join("") }</article>")
+        end
+
+        [level, [fragment]]
+      end
+
+      self.fragment = Brief::Document::Section::Builder.run(mapping, low: lowest_level, high: highest_level)
+    end
+
+    def levels
+      l = fragment.css("[data-level]").map {|el| el.attr('data-level').to_i }
+      l.reject!(&:nil?)
+      l.reject! {|v| v.to_i == 0 }
+      l.uniq!
+      l
+    end
+
+    def highest_level
+      levels.max
+    end
+
+    def lowest_level
+      levels.min
+    end
+
+    def headings_at_level(level, options={})
+      matches = heading_elements.select {|el| el.level.to_i == level.to_i }
+
+      if options[:text]
+        matches.map(&:text)
+      else
+        matches
+      end
+    end
+
+    def heading_with_text(text)
+      headings_with_text(text).tap do |results|
+        raise 'no section found with content: ' + text if results.length == 0
+        raise 'more than one section found with content: ' + text if results.length >= 2
+
+      end.first
+    end
+
+    def headings_with_text(text)
+      heading_elements.select do |el|
+        el.heading.to_s.strip == text.to_s.strip
+      end
+    end
+
+    def find_heading_by(level, heading)
+      heading_elements.find do |el|
+        el.level.to_s == level.to_s && heading.to_s.strip == el.heading.to_s.strip
+      end
+    end
+
+    def heading_elements
+      @heading_elements ||= fragment.css("h1,h2,h3,h4,h5,h6").map do |el|
+        if el.attr('data-level').to_i > 0
+          {
+            level: el.attr('data-level'),
+            heading: el.attr('data-heading'),
+            element: el
+          }.to_mash
+        end
+      end.compact
+    end
+
+    class Util
+      class << self
+        def is_header?(element)
+          element.name.to_s.downcase.match(/^h\d$/)
+        end
+
+        def level(element)
+          element.name.to_s.gsub(/^h/i,'').to_i
+        end
+      end
+    end
+  end
+end

data/lib/brief/document.rb

@@ -3,36 +3,72 @@ module Brief
     include Brief::Document::Rendering
     include Brief::Document::FrontMatter
 
-    attr_accessor :path, :content, :frontmatter
+    attr_accessor :path, :content, :frontmatter, :raw_content
 
     def initialize(path, options={})
       @path = Pathname(path)
       @options = options
 
       if self.path.exist?
-        content
+        @raw_content = path.read
         load_frontmatter
       end
 
       self.model_class.try(:models).try(:<<, to_model) unless model_instance_registered?
     end
 
-    def content
-      @content ||= path.read
+    def data
+      frontmatter
+    end
+
+    def sections
+      mappings = model_class.section_mappings
+
+      @sections = {}.to_mash
+
+      mappings.each do |name, mapping|
+        fragment = css("section[data-heading='#{name}']").first
+        @sections[name.parameterize.downcase.underscore] = Brief::Document::Section.new(name, fragment, mapping)
+      end
+
+      @sections
+    end
+
+    # Shortcut for querying the rendered HTML by css selectors.
+    #
+    # This will allow for model data attributes to be pulled from the
+    # document contents.
+    #
+    # Returns a Nokogiri::HTML::Element
+    def css(*args, &block)
+      parser.send(:css, *args, &block)
+    end
+
+    # Returns a Nokogiri::HTML::Element
+    def at(*args, &block)
+      parser.send(:at, *args, &block)
     end
 
     def extract_content(*args)
       options = args.extract_options!
-      args    = options[:args] if options.is_a?(Hash) && options.key?(:args)
+      args    = options.delete(:args) if options.is_a?(Hash) && options.key?(:args)
 
       case
-      when args.length == 1 && args.first.is_a?(String)
-        css(args.first).try(:text).to_s
+      when options.empty? && args.length == 1 && args.first.is_a?(String)
+        results = css(args.first)
+        results = results.first if results.length > 1 && args.first.match(/:first-of-type/)
+        results.try(:text).to_s
+      else
+        binding.pry
       end
     end
 
-    def data
-      frontmatter
+    def relative_path_identifier
+      if Brief.case
+        path.relative_path_from(Brief.case.root)
+      else
+        path.to_s
+      end
     end
 
     def extension
@@ -60,6 +96,21 @@ module Brief
       super || data.respond_to?(method) || data.key?(method)
     end
 
+    def structure
+      @structure_analyzer ||= Brief::Document::Structure.new(fragment, self.raw_content.lines.to_a)
+    end
+
+    def parser
+      @parser ||= begin
+                    structure.prescan
+                    structure.create_wrappers
+                  end
+    end
+
+    def fragment
+      @fragment ||= Nokogiri::HTML.fragment(to_raw_html)
+    end
+
     def method_missing(meth, *args, &block)
       if data.respond_to?(meth)
         data.send(meth, *args, &block)
@@ -67,7 +118,6 @@ module Brief
         super
       end
     end
-
   end
 end
 

data/lib/brief/dsl.rb

@@ -13,6 +13,16 @@ module Brief
       definition.validate!
     end
 
+    # defines a method on the model instance named after the identifier
+    # and then creates a CLI command matching that, so for example:
+    #
+    # given a model called 'Post' and an action named 'publish' the
+    # brief CLI executable will respond to:
+    #
+    #   brief publish posts PATH_GLOB
+    #
+    # this will find all of the Post models from the documents matching PATH_GLOB
+    # and call the publish method on them
     def action(identifier, options={}, &block)
       Object.class.class_eval do
         command "#{identifier}" do |c|

data/lib/brief/model/definition.rb

@@ -5,13 +5,15 @@ module Brief
                   :metadata_schema,
                   :content_schema,
                   :options,
-                  :defined_helpers
+                  :defined_helpers,
+                  :section_mappings
 
     def initialize(name, options={})
       @name             = name
       @options          = options
       @type_alias       = options.fetch(:type_alias) { name.downcase.parameterize.gsub(/-/,'_') }
       @metadata_schema  = {}.to_mash
+      @section_mappings = {}.to_mash
       @content_schema   = {attributes:{}}.to_mash
       @model_class      = options[:model_class]
     end
@@ -107,15 +109,22 @@ module Brief
       @current == :content
     end
 
+    def section_mapping(identifier)
+      section_mappings.fetch(identifier)
+    end
+
     def method_missing(meth, *args, &block)
       args = args.dup
 
       if inside_content?
-        if meth.to_s == :define_section
-
+        if meth.to_sym == :define_section
+          opts = args.extract_options!
+          identifier = args.first
+          self.section_mappings[identifier] ||= Brief::Document::Section::Mapping.new(identifier, opts)
+          section_mapping(identifier).instance_eval(&block) if block
+        else
+          self.content_schema.attributes[meth] = {args: args, block: block}
         end
-
-        self.content_schema.attributes[meth] = {args: args, block: block}
       elsif inside_meta?
         if args.first.is_a?(Hash)
           args.unshift(String)

data/lib/brief/model.rb

@@ -141,9 +141,17 @@ module Brief
         @definition
       end
 
+      def section_mapping(*args)
+        definition.send(:section_mapping, *args)
+      end
+
+      def section_mappings(*args)
+        definition.send(:section_mappings, *args)
+      end
+
       def method_missing(meth, *args, &block)
         if %w(meta content actions helpers).include?(meth.to_s)
-          definition.send(meth, &block)
+          definition.send(meth, *args, &block)
           finalize
         elsif meth.to_s.match(/^on_(.*)_change$/)
           create_change_handler($1, *args, &block)

data/lib/brief/repository.rb

@@ -40,7 +40,7 @@ module Brief
     end
 
     def document_paths
-      Dir[root.join("**/*.md").to_s]
+      Dir[root.join("**/*.md").to_s].map {|p| Pathname(p) }
     end
 
     def self.define_document_finder_methods

data/lib/brief/version.rb

@@ -1,3 +1,3 @@
 module Brief
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/brief.rb

@@ -40,6 +40,13 @@ module Brief
   def self.load_models(from_folder=nil)
     Brief::Model.load_all(from_folder: from_folder)
   end
+
+  # Adapters for Rails, Middleman, or Jekyll apps
+  def self.activate_adapter(identifier)
+    require "brief/adapters/#{ identifier }"
+    adapter = (Brief::Adapters.const_get(identifier.camelize) rescue nil)
+    adapter.try(:activate_adapter)
+  end
 end
 
 require "brief/core_ext"
@@ -49,6 +56,10 @@ require "brief/configuration"
 require "brief/document/rendering"
 require "brief/document/front_matter"
 require "brief/document/content_extractor"
+require "brief/document/structure"
+require "brief/document/section"
+require "brief/document/section/mapping"
+require "brief/document/section/builder"
 require "brief/document"
 require "brief/document_mapper"
 require "brief/repository"

data/spec/fixtures/example/docs/epic.html.md

@@ -14,6 +14,12 @@ which contains user stories and such.
 
 ## A user wants to write epics
 
+As a **User** I want to **write epics** so that I can **write a bunch of user stories in one file**
+
 ## A user wants to annotate wireframes
 
+As a **User** I want to  **annotate wireframes** so that I can **augment diagrams with targeted explanations**
+
 ## A user wants to provide details about domain concepts
+
+As a **User** I want to **provide some detailed explanations of domain concepts** so that I can **augment diagrams with targeted explanations**

data/spec/fixtures/example/models/epic.rb

@@ -8,10 +8,17 @@ class Brief::Epic
   end
 
   content do
-    title "h1:first-child"
+    # have to do this so that the user stories section h1 doesnt get confused
+    title "h1:first-of-type"
 
     define_section "User Stories" do
-      has_many :user_stories, "h2" => "title", "p:first-child" => "paragraph"
+      # NOT YET Implemented
+      each("h2").is_a :user_story
+
+      each("h2").has(:title     => "h2",
+                     :paragraph => "p:first-of-type",
+                     :components   => "p:first-of-type strong"
+                    )
     end
   end
 

data/spec/fixtures/structures/one.html.md

@@ -0,0 +1,37 @@
+---
+type: epic
+status: published
+---
+This is a paragraph
+
+This is another paragraph
+
+This is a list:
+
+- list one
+- list two
+- list three
+
+```ruby
+# SOME CODE
+```
+
+# User Stories
+
+## Story Title One
+
+As a **User** I would like to **Behavior** so that I can **goal**
+
+## Story Title Two
+
+As a **User** I would like to **Behavior** so that I can **goal**
+
+## Story Title Three
+
+As a **User** I would like to **Behavior** so that I can **goal**
+
+# Diagrams
+
+- diagram one
+- diagram one
+- diagram one

data/spec/fixtures/structures/three.html.md

@@ -0,0 +1,20 @@
+---
+type: epic
+status: published
+---
+
+# This is the title
+
+This is a paragraph
+
+This is another paragraph
+
+This is a list:
+
+- list one
+- list two
+- list three
+
+```ruby
+# SOME CODE
+```

data/spec/fixtures/structures/two.html.md

@@ -0,0 +1,40 @@
+---
+type: epic
+status: published
+---
+
+# This is the title
+
+This is a paragraph
+
+This is another paragraph
+
+This is a list:
+
+- list one
+- list two
+- list three
+
+```ruby
+# SOME CODE
+```
+
+# User Stories
+
+## Story Title One
+
+As a **User** I would like to **Behavior** so that I can **goal**
+
+## Story Title Two
+
+As a **User** I would like to **Behavior** so that I can **goal**
+
+## Story Title Three
+
+As a **User** I would like to **Behavior** so that I can **goal**
+
+# Diagrams
+
+- diagram one
+- diagram one
+- diagram one

data/spec/lib/brief/document_spec.rb

@@ -7,21 +7,37 @@ describe "The Brief Document" do
   end
 
   it "renders html" do
-    expect(sample.to_html).to include("<h1>User Stories</h1>")
+    expect(sample.to_html).to match(/h1.*User Stories.*h1\>/)
   end
 
   it "parses the html" do
     expect(sample.css("h1").length).to eq(2)
   end
 
+
   it "deserializes YAML frontmatter into attributes" do
     expect(sample.frontmatter.type).to eq("epic")
   end
 
   context "Content Extraction" do
     it "extracts content from a css selector" do
-      extracted = sample.extract_content(:args => ["h1:first-child"])
+      extracted = sample.extract_content(:args => ["h1:first-of-type"])
       expect(extracted).to eq("Blueprint Epic Example")
     end
   end
+
+  context "defining sections" do
+    it "lets me define content sections" do
+      expect(sample.sections).not_to be_empty
+      expect(sample.sections.user_stories).to be_present
+      expect(sample.sections.user_stories.fragment.name).to eq("section")
+      expect(sample.sections.user_stories.fragment.css("article").length).to eq(3)
+    end
+
+    it "gives me an array of items underneath the section filled with the key value mappings i laid out" do
+      items = sample.sections.user_stories.items
+      expect(items.length).to eq(3)
+      expect(items.map(&:components).map(&:first).uniq).to eq(["User"])
+    end
+  end
 end

data/spec/lib/brief/model_spec.rb

@@ -102,4 +102,11 @@ describe "The Brief Model" do
       expect(user_story.class.defined_actions).to include(:custom_action)
     end
   end
+
+  context "Section Mappings" do
+    it "defines a section mapping for User Stories" do
+      mapping = epic.class.section_mapping("User Stories")
+      expect(mapping).to be_a(Brief::Document::Section::Mapping)
+    end
+  end
 end

data/spec/lib/brief/rendering_spec.rb

@@ -0,0 +1,24 @@
+require "spec_helper"
+
+describe "Brief HTML Rendering" do
+  let(:sample) do
+    path = Brief.example_path.join("docs","epic.html.md")
+    Brief::Document.new(path)
+  end
+
+  it "wraps the document with some identifying details" do
+    expect(sample.to_html).to include("docs/epic.html.md")
+  end
+
+  it "wraps the higher level headings under section elements" do
+    expect(sample.css("section").length).to eq(2)
+  end
+
+  it "wraps the lower level headings under article elements" do
+    expect(sample.css("article").length).to eq(3)
+  end
+
+  it "nests the articles under the parent section" do
+    expect(sample.css("section article").length).to eq(3)
+  end
+end

data/spec/lib/brief/section_builder_spec.rb

@@ -0,0 +1,22 @@
+require "spec_helper"
+
+describe "The Section Builder" do
+  let(:builder) do
+    inputs = [
+      [1, ["<section><h1>Heading</h1></section>"]],
+      [1, ["<section><h1>Section Heading</h1></section>"]],
+      [2, ["<article><h2>a</h2></article>"]],
+      [2, ["<article><h2>b</h2></article>"]],
+      [2, ["<article><h2>c</h2></article>"]],
+      [1, ["<section><h1>Footer</h1></section>"]]
+    ]
+
+    Brief::Document::Section::Builder.new(inputs)
+  end
+
+  it "collapses the HTML into sections for us" do
+    expect(builder.to_fragment.css("section h1").count).to eq(3)
+    expect(builder.to_fragment.css("section article").count).to eq(3)
+  end
+
+end

data/spec/lib/brief/structure_spec.rb

@@ -0,0 +1,30 @@
+require "spec_helper"
+
+describe "Document Structure Information" do
+  let(:sample) do
+    path = Brief.example_path.join("docs","epic.html.md")
+    Brief::Document.new(path)
+  end
+
+  let(:one) do
+    path = Brief.spec_root.join("fixtures","structures", "one.html.md")
+    Brief::Document.new(path)
+  end
+
+  let(:two) do
+    path = Brief.spec_root.join("fixtures","structures", "two.html.md")
+    Brief::Document.new(path)
+  end
+
+  let(:three) do
+    path = Brief.spec_root.join("fixtures","structures", "three.html.md")
+    Brief::Document.new(path)
+  end
+
+  context "Mapping markdown source to output html" do
+    it "should put the line numbers on the headings" do
+      el = sample.css("h1").first
+      expect(el.attr('data-line-number')).to eq("8")
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brief
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Jonathan Soeder
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-07 00:00:00.000000000 Z
+date: 2015-01-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -216,6 +216,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -228,6 +229,7 @@ files:
 - examples/blog/docs/an-intro-to-brief.html.md
 - lib/.DS_Store
 - lib/brief.rb
+- lib/brief/adapters/middleman.rb
 - lib/brief/briefcase.rb
 - lib/brief/cli/change.rb
 - lib/brief/cli/init.rb
@@ -238,6 +240,10 @@ files:
 - lib/brief/document/content_extractor.rb
 - lib/brief/document/front_matter.rb
 - lib/brief/document/rendering.rb
+- lib/brief/document/section.rb
+- lib/brief/document/section/builder.rb
+- lib/brief/document/section/mapping.rb
+- lib/brief/document/structure.rb
 - lib/brief/document_mapper.rb
 - lib/brief/dsl.rb
 - lib/brief/model.rb
@@ -255,12 +261,18 @@ files:
 - spec/fixtures/example/docs/user_story.html.md
 - spec/fixtures/example/docs/wireframe.html.md
 - spec/fixtures/example/models/epic.rb
+- spec/fixtures/structures/one.html.md
+- spec/fixtures/structures/three.html.md
+- spec/fixtures/structures/two.html.md
 - spec/lib/brief/briefcase_spec.rb
 - spec/lib/brief/document_spec.rb
 - spec/lib/brief/dsl_spec.rb
 - spec/lib/brief/model_spec.rb
 - spec/lib/brief/persistence_spec.rb
+- spec/lib/brief/rendering_spec.rb
 - spec/lib/brief/repository_spec.rb
+- spec/lib/brief/section_builder_spec.rb
+- spec/lib/brief/structure_spec.rb
 - spec/spec_helper.rb
 - spec/support/test_helpers.rb
 - tasks/brief/release.rake
@@ -298,12 +310,18 @@ test_files:
 - spec/fixtures/example/docs/user_story.html.md
 - spec/fixtures/example/docs/wireframe.html.md
 - spec/fixtures/example/models/epic.rb
+- spec/fixtures/structures/one.html.md
+- spec/fixtures/structures/three.html.md
+- spec/fixtures/structures/two.html.md
 - spec/lib/brief/briefcase_spec.rb
 - spec/lib/brief/document_spec.rb
 - spec/lib/brief/dsl_spec.rb
 - spec/lib/brief/model_spec.rb
 - spec/lib/brief/persistence_spec.rb
+- spec/lib/brief/rendering_spec.rb
 - spec/lib/brief/repository_spec.rb
+- spec/lib/brief/section_builder_spec.rb
+- spec/lib/brief/structure_spec.rb
 - spec/spec_helper.rb
 - spec/support/test_helpers.rb
 has_rdoc: