hologram 1.2.0 → 1.3.0

data/lib/hologram/document_block.rb

@@ -1,6 +1,6 @@
 module Hologram
   class DocumentBlock
-    COMMENT_REGEX = /^\s*---\s(.*?)\s---$/m
+    COMMENT_REGEX = /^\s*---\s(.*?)\s---[\r]?$/m
 
     attr_accessor :name, :parent, :children, :title, :categories, :markdown, :config, :heading, :errors
 
@@ -26,7 +26,7 @@ module Hologram
       @config   = config
       @name     = config['name']
       @categories = Array(config['category'] || config['categories'])
-      @title    = config['title']
+      @title    = h(config['title'])
       @parent   = config['parent']
       @markdown = markdown
 
@@ -51,8 +51,26 @@ module Hologram
     end
 
     # sets the header tag based on how deep your nesting is
-    def markdown_with_heading(heading = 1)
-      "\n\n<h#{heading.to_s} id=\"#{@name}\">#{@title}</h#{heading.to_s}>" + @markdown
+
+    def markdown_with_heading(heading = 1, opts={})
+      include_sub_nav = opts[:include_sub_nav] || false
+
+      output = "\n\n<h#{heading.to_s} id=\"#{@name}\" class=\"#{css_class_name}\">#{@title}</h#{heading.to_s}>"
+      if include_sub_nav && !children.empty?
+        output += "\n<ul class=\"section-nav\">"
+        children.values.each do |child|
+          output += "\n  <li><a href=\"\##{child.name}\">#{child.title}</a></li>"
+        end
+        output += "\n</ul>\n"
+      end
+      output += @markdown
+      output
+    end
+
+    private
+
+    def css_class_name
+      'styleguide'
     end
   end
 end

data/lib/hologram/link_helper.rb

@@ -0,0 +1,18 @@
+module Hologram
+  class LinkHelper
+    def initialize(pages)
+      @all_links = {}
+      pages.each do |page|
+        page[:component_names].each do |component_name|
+          @all_links[component_name] ||= "#{page[:name]}\##{component_name}"
+        end
+      end
+    end
+
+    attr_reader :all_links
+
+    def link_for(component_name)
+      all_links[component_name]
+    end
+  end
+end

data/lib/hologram/markdown_renderer.rb

@@ -1,52 +1,73 @@
+require 'hologram/block_code_renderer'
+
+include ERB::Util
+
 module Hologram
   class MarkdownRenderer < Redcarpet::Render::HTML
-    def block_code(code, language)
-      formatter = Rouge::Formatters::HTML.new(wrap: false)
-      if language and language.include?('example')
-        if language.include?('js')
-          lexer = Rouge::Lexer.find('js')
-          # first actually insert the code in the docs so that it will run and make our example work.
-          '<script>' + code + '</script> <div class="codeBlock jsExample"><div class="highlight"><pre>' + formatter.format(lexer.lex(code)) + '</pre></div></div>'
-        else
-          lexer = Rouge::Lexer.find(get_lexer(language))
-          '<div class="codeExample">' + '<div class="exampleOutput">' + render_html(code, language) + '</div>' + '<div class="codeBlock"><div class="highlight"><pre>' + formatter.format(lexer.lex(code)) + '</pre></div></div>' + '</div>'
-        end
+    def initialize(opts={})
+      super(opts)
+      @link_helper = opts[:link_helper]
+    end
+
+    def list(contents, list_type)
+      case list_type
+      when :ordered
+        "<ol class=\"#{css_class_name}\">#{contents}</ol>"
       else
-        lexer = Rouge::Lexer.find_fancy('guess', code)
-        '<div class="codeBlock"><div class="highlight"><pre>' + formatter.format(lexer.lex(code)) + '</pre></div></div>'
+        "<ul class=\"#{css_class_name}\">#{contents}</ul>"
       end
     end
 
-    private
-    def render_html(code, language)
-      case language
-        when 'haml_example'
-          safe_require('haml', language)
-          return Haml::Engine.new(code.strip).render(template_rendering_scope, {})
-        else
-          code
-      end
+    def paragraph(text)
+      "<p class=\"#{css_class_name}\">#{text}</p>"
+    end
+
+    def table(header, body)
+      "<table class=\"#{css_class_name}\"> #{header} #{body} </table>"
+    end
+
+    def codespan(code)
+      "<code class=\"#{css_class_name}\">#{html_escape(code)}</code>"
+    end
+
+    def link(link, title, content)
+      "<a class=\"#{css_class_name}\" href=\"#{link}\" title=\"#{title || link}\">#{content}</a>"
     end
 
-    def template_rendering_scope
-      Object.new
+    def block_code(code, language)
+      BlockCodeRenderer.new(code, language).render
     end
 
-    def get_lexer(language)
-      case language
-        when 'haml_example'
-          'haml'
-        else
-          'html'
+    def preprocess(full_document)
+      if link_helper
+        link_defs + "\n" + full_document
+      else
+        full_document
       end
     end
 
-    def safe_require(templating_library, language)
-      begin
-        require templating_library
-      rescue LoadError
-        raise "#{templating_library} must be present for you to use #{language}"
+    def postprocess(full_document)
+      invalid_links = full_document.scan(/(?: \[ [\s\w]+ \]){2}/x)
+
+      invalid_links.each do |invalid_link|
+        component = /\[.+\]/.match(invalid_link)[1]
+        DisplayMessage.warning("Invalid reference link - #{invalid_link}." +
+                               "Presumably the component #{component} does not exist.")
       end
+
+      full_document
+    end
+
+    def css_class_name
+      'styleguide'
+    end
+
+    private
+
+    attr_reader :link_helper
+
+    def link_defs
+      @_link_defs ||= link_helper.all_links.map { |c_name, link| "[#{c_name}]: #{link}" }.join("\n")
     end
   end
 end

data/lib/hologram/version.rb

@@ -25,5 +25,5 @@
 # ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 module Hologram
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/template/code_example_templates/js_example_template.html.erb

@@ -0,0 +1,7 @@
+<script><%= rendered_example %></script>
+<div class="codeBlock jsExample">
+  <div class="highlight">
+    <pre><%= code_example %></pre>
+  </div>
+</div>
+

data/lib/template/code_example_templates/jsx_example_template.html.erb

@@ -0,0 +1,7 @@
+<script type='text/jsx'><%= rendered_example %></script>
+<div class="codeBlock jsExample">
+  <div class="highlight">
+    <pre><%= code_example %></pre>
+  </div>
+</div>
+

data/lib/template/code_example_templates/markup_example_template.html.erb

@@ -0,0 +1,10 @@
+<div class="codeExample">
+  <div class="exampleOutput">
+    <%= rendered_example %>
+  </div>
+  <div class="codeBlock">
+    <div class="highlight">
+      <pre><%= code_example %></pre>
+    </div>
+  </div>
+</div>

data/lib/template/code_example_templates/markup_table_template.html.erb

@@ -0,0 +1,23 @@
+<div class="codeTable">
+  <table>
+    <tbody>
+      <% examples.each do |example| %>
+        <tr>
+          <th>
+            <div class="exampleOutput">
+              <%= example.rendered_example %>
+            </div>
+          </th>
+          <td>
+            <div class="codeBlock">
+              <div class="highlight">
+                <pre><%= example.code_example %></pre>
+              </div>
+            </div>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+

data/lib/template/hologram_config.yml

@@ -12,6 +12,17 @@ destination: ./docs
 # You may put doc related assets here too: images, css, etc.
 documentation_assets: ./doc_assets
 
+# The folder that contains templates for rendering code examples.
+# If you want to change the way code examples appear in the styleguide,
+# modify the files in this folder
+code_example_templates: ./code_example_templates
+
+# The folder that contains custom code example renderers.
+# If you want to create additional renderers that are not provided
+# by Hologram (i.e. coffeescript renderer, jade renderer, etc)
+# place them in this folder
+code_example_renderers: ./code_example_renderers
+
 # Any other asset folders that need to be copied to the destination
 # folder. Typically this will include the css that you are trying to
 # document. May also include additional folders as needed.
@@ -22,3 +33,15 @@ dependencies:
 # Alternatively, you may have an index.md in the documentation assets
 # folder instead of specifying this config.
 index: basics
+
+# To additionally output navigation for top level sections, set the value to
+# 'section'. To output navigation for sub-sections,
+# set the value to `all`
+nav_level: all
+
+# Hologram displays warnings when there are issues with your docs
+# (e.g. if a component's parent is not found, if the _header.html and/or
+#  _footer.html files aren't found)
+# If you want Hologram to exit on these warnings, set the value to 'true'
+# (Default value is 'false')
+exit_on_warnings: false

data/spec/block_code_renderer_spec.rb

@@ -0,0 +1,279 @@
+require 'spec_helper'
+require 'hologram/block_code_renderer'
+require 'haml'
+require 'securerandom'
+
+Hologram::CodeExampleRenderer.load_renderers_and_templates
+
+describe Hologram::BlockCodeRenderer do
+  describe '#render' do
+    subject { Hologram::BlockCodeRenderer.new(code, markdown_language).render.strip }
+
+    context 'expected language' do
+      context 'react' do
+        let(:language) { 'react' }
+        let(:code) { '<ReactExample property="value">Example</ReactExample>' }
+
+        context 'when the language is a react_example' do
+          let(:markdown_language) { 'react_example' }
+          let(:div_id) { 'randomId' }
+
+          before :each do
+            SecureRandom.stub('hex').and_return(div_id);
+          end
+
+          it { is_expected.to eq [
+            "<div class=\"codeExample\">",
+            "  <div class=\"exampleOutput\">",
+            "    <div id=\"#{div_id}\"></div>",
+            "<script type=\"text/jsx\">",
+            "  React.render(",
+            "    <ReactExample property=\"value\">Example</ReactExample>,",
+            "    document.getElementById('#{div_id}')",
+            "  );",
+            "</script>",
+            "  </div>",
+            "  <div class=\"codeBlock\">",
+            "    <div class=\"highlight\">",
+            "      <pre><span class=\"nt\">&lt;ReactExample</span> <span class=\"na\">property=</span><span class=\"s\">\"value\"</span><span class=\"nt\">&gt;</span>Example<span class=\"nt\">&lt;/ReactExample&gt;</span></pre>",
+            "    </div>",
+            "  </div>",
+            "</div>"
+          ].join("\n") }
+        end
+      end
+
+      context 'slim' do
+        let(:language) { 'slim' }
+        let(:code) { 'h1 Markup Example' }
+
+        context 'when the language is a slim_example' do
+          let(:markdown_language) { 'slim_example' }
+
+          it { is_expected.to eq [
+            "<div class=\"codeExample\">",
+            "  <div class=\"exampleOutput\">",
+            "    <h1>Markup Example</h1>",
+            "  </div>",
+            "  <div class=\"codeBlock\">",
+            "    <div class=\"highlight\">",
+            "      <pre><span class=\"nt\">h1</span><span class=\"w\"> </span>Markup<span class=\"w\"> </span>Example</pre>",
+            "    </div>",
+            "  </div>",
+            "</div>",
+          ].join("\n") }
+        end
+      end
+
+      context 'haml' do
+        let(:language) { 'haml' }
+        let(:code) { '%h1 Example' }
+
+        context 'when the language is a haml_example' do
+          let(:markdown_language) { 'haml_example' }
+
+          it { is_expected.to eq [
+            "<div class=\"codeExample\">",
+            "  <div class=\"exampleOutput\">",
+            "    <h1>Example</h1>\n",
+            "  </div>",
+            "  <div class=\"codeBlock\">",
+            "    <div class=\"highlight\">",
+            "      <pre><span class=\"nt\">%h1</span> Example</pre>",
+            "    </div>",
+            "  </div>",
+            "</div>",
+          ].join("\n") }
+        end
+
+        context 'when the language is a haml_example_table' do
+          let(:markdown_language) { 'haml_example_table' }
+          let(:code) { [
+            ".spinner-lg",
+            "  %i.fa.fa-spin",
+            "",
+            "%h1 Example"
+          ].join("\n") }
+
+          it { is_expected.to eq [
+            "<div class=\"codeTable\">",
+            "  <table>",
+            "    <tbody>",
+            "      ",
+            "        <tr>",
+            "          <th>",
+            "            <div class=\"exampleOutput\">",
+            "              <div class='spinner-lg'>",
+            "  <i class='fa fa-spin'></i>",
+            "</div>",
+            "",
+            "            </div>",
+            "          </th>",
+            "          <td>",
+            "            <div class=\"codeBlock\">",
+            "              <div class=\"highlight\">",
+            "                <pre><span class=\"nc\">.spinner-lg</span>",
+            "  <span class=\"nt\">%i</span><span class=\"nc\">.fa.fa-spin</span></pre>",
+            "              </div>",
+            "            </div>",
+            "          </td>",
+            "        </tr>",
+            "      ",
+            "        <tr>",
+            "          <th>",
+            "            <div class=\"exampleOutput\">",
+            "              <h1>Example</h1>",
+            "",
+            "            </div>",
+            "          </th>",
+            "          <td>",
+            "            <div class=\"codeBlock\">",
+            "              <div class=\"highlight\">",
+            "                <pre><span class=\"nt\">%h1</span> Example</pre>",
+            "              </div>",
+            "            </div>",
+            "          </td>",
+            "        </tr>",
+            "      ",
+            "    </tbody>",
+            "  </table>",
+            "</div>"
+          ].join("\n") }
+        end
+      end
+
+      context 'html' do
+        let(:language) { 'html' }
+        let(:code) { '<h2></h2>' }
+        let(:formatted_code) { 'formatted h2' }
+        context 'when the language is html_example' do
+          let(:markdown_language) { 'html_example' }
+
+          it { is_expected.to eq [
+            "<div class=\"codeExample\">",
+            "  <div class=\"exampleOutput\">",
+            "    <h2></h2>",
+            "  </div>",
+            "  <div class=\"codeBlock\">",
+            "    <div class=\"highlight\">",
+            "      <pre><span class=\"nt\">&lt;h2&gt;&lt;/h2&gt;</span></pre>",
+            "    </div>",
+            "  </div>",
+            "</div>",
+          ].join("\n") }
+        end
+
+        context 'when the language is a html_example_table' do
+          let(:markdown_language) { 'html_example_table' }
+          let(:code) { [
+            "<div class='spinner-lg'></div>",
+            "",
+            "<h1>Example</h1>"
+          ].join("\n") }
+
+          it { is_expected.to eq [
+            "<div class=\"codeTable\">",
+            "  <table>",
+            "    <tbody>",
+            "      ",
+            "        <tr>",
+            "          <th>",
+            "            <div class=\"exampleOutput\">",
+            "              <div class='spinner-lg'></div>",
+            "            </div>",
+            "          </th>",
+            "          <td>",
+            "            <div class=\"codeBlock\">",
+            "              <div class=\"highlight\">",
+            "                <pre><span class=\"nt\">&lt;div</span> <span class=\"na\">class=</span><span class=\"s\">'spinner-lg'</span><span class=\"nt\">&gt;&lt;/div&gt;</span></pre>",
+            "              </div>",
+            "            </div>",
+            "          </td>",
+            "        </tr>",
+            "      ",
+            "        <tr>",
+            "          <th>",
+            "            <div class=\"exampleOutput\">",
+            "              <h1>Example</h1>",
+            "            </div>",
+            "          </th>",
+            "          <td>",
+            "            <div class=\"codeBlock\">",
+            "              <div class=\"highlight\">",
+            "                <pre><span class=\"nt\">&lt;h1&gt;</span>Example<span class=\"nt\">&lt;/h1&gt;</span></pre>",
+            "              </div>",
+            "            </div>",
+            "          </td>",
+            "        </tr>",
+            "      ",
+            "    </tbody>",
+            "  </table>",
+            "</div>"
+          ].join("\n") }
+        end
+      end
+
+      context 'js_example' do
+        let(:language) { 'js' }
+        let(:markdown_language) { 'js_example' }
+        let(:code) { '$(document).ready(function() {});' }
+
+        it "inserts the code into the docs so that it will run and make the example work" do
+          expect(subject).to include "<script>$(document).ready(function() {});</script>"
+        end
+
+        it { is_expected.to include [
+          "<div class=\"codeBlock jsExample\">",
+          "  <div class=\"highlight\">",
+          "    <pre><span class=\"nx\">$</span><span class=\"p\">(</span><span class=\"nb\">document</span><span class=\"p\">).</span><span class=\"nx\">ready</span><span class=\"p\">(</span><span class=\"kd\">function</span><span class=\"p\">()</span> <span class=\"p\">{});</span></pre>",
+          "  </div>",
+          "</div>",
+        ].join("\n") }
+      end
+
+      context 'jsx_example' do
+        let(:language) { 'jsx' }
+        let(:markdown_language) { 'jsx_example' }
+        let(:code) { '$(document).ready(function () { React.render(<div className="foo"></div>) });' }
+
+        it "inserts the code into the docs so that it will run and make the example work" do
+          expect(subject).to include "<script type='text/jsx'>$(document).ready(function () { React.render(<div className=\"foo\"></div>) });</script>"
+        end
+
+        it { is_expected.to include [
+          "<div class=\"codeBlock jsExample\">",
+          "  <div class=\"highlight\">",
+          "    <pre>$(document).ready(function () { React.render(<span class=\"nt\">&lt;div</span> <span class=\"na\">className=</span><span class=\"s\">\"foo\"</span><span class=\"nt\">&gt;&lt;/div&gt;</span>) });</pre>",
+          "  </div>",
+          "</div>",
+        ].join("\n") }
+      end
+    end
+
+    context 'unexpected language' do
+      let(:markdown_language) { 'fortran' }
+      let(:code) { 'goto 12' }
+
+      it { is_expected.to eq [
+        "<div class=\"codeBlock\">",
+        "  <div class=\"highlight\">",
+        "    <pre>goto 12</pre>",
+        "  </div>",
+        "</div>",
+      ].join("\n") }
+    end
+
+    context 'no language' do
+      let(:markdown_language) { nil }
+      let(:code) { 'unknown code' }
+
+      it { is_expected.to eq [
+        "<div class=\"codeBlock\">",
+        "  <div class=\"highlight\">",
+        "    <pre>unknown code</pre>",
+        "  </div>",
+        "</div>",
+      ].join("\n") }
+    end
+  end
+end