Custom code example templates and renderers

[gpleiss]

This PR address #170

Adds a new config option: code_example_templates. If a user wants to change the way code examples are rendered in the styleguide, they can add custom templates to this folder. Hologram will look for the following 4 templates:

• markup_example_template.html.erb - used for html, haml and slim examples
• markup_table_template.html.erb - used for multiple html, haml and slim examples layed out in a table
• js_example_template.html.erb - used for js examples
• jsx_example_template.html.erb - used for jsx examples

As an example, the markup_example_template looks like this:

<div class="codeExample">
  <div class="exampleOutput">
    <%= rendered_example %>
  </div>
  <div class="codeBlock">
    <div class="highlight">
      <pre>
        <%= code_example %>
      </pre>
    </div>
  </div>
</div>

Hologram will fall back on default templates if a user doesn't specify a folder for code_example_templates in their config file (or if certain template files are not found). So this isn't a breaking change :dancer:

This PR restructures the BlockCodeRenderer (again... :cold_sweat: ), but I think that the code is now much more modular. I think this new code will make it easier to get Hologram to the point where users can add their own languages in a simpler way.

Best! Geoff (cc/ @stubbornella @bebepeng @pivotal-plech)

[gpleiss]

Fixed the CI errors. Had to do with the way we were requiring files.

[jdcantrell]

Oh nice, I was going to take a look at that later today. I'll look this over tonight and get it merged. Thanks!

[gpleiss]

Actually, can we hold off on merging this? We're working on something right now that will make it really easy to add custom renderers which might change the code a bit.

[jdcantrell]

Yup, np, let me know when you're set :-)

[gpleiss]

Okay, I thought what I was adding would be a simple change. Instead this PR got a little crazy. Let me know if it's too much, and I can try to break it up a bit.

This PR now adds the ability for users to add their own custom code example renderers.

For example, let's say I want to render coffeescript examples in my styleguide. Instead of modifying the BlockCodeRenderer, I can use the (new) code example renderer factory:

require 'coffee-script'

Hologram::CodeExampleRenderer::Factory.define('coffee') do
  example_template 'js_example_template'
  table_template 'js_table_template'

  lexer { Rouge::Lexer.find(:coffee) }

  rendered_example do |code|
    CoffeeScript.compile(code)
  end
end

This code is placed in a ruby file in my code\_example\_renderer folder (a new config option). E.g. this file could be called (i.e. ./code_example_renderers/coffee_renderer.rb) . Now I can render coffeescript examples in my styleguide.

We can render single coffeescript examples...

```coffee_example
$('#myDiv').click ->
    alert 'Oh wow we are rendering coffee script'

Or we can render coffeescript tables...

#code goes here

Details on how to use the factory are in the readme.

This resulted in lots of code changes (sorry it's kind of crazy), but I think this interface is pretty clean and allow the styleguide to be extremely customizable without having to do crazy things with the block code renderer. Let me know what you think! :grin:

[shoesforindustry]

Seems like a very good way to go, it was one of the reasons I stopped using Hologram, but I think I'm about to take another look...

[stubbornella]

Overall, this looks like a great change, it seems like it will make it a lot easier to add custom renderers and accept PRs for custom renderers without feeling like it will complicate the basic setup. That said, holy enormous PR @gpleiss! This broke my brain.

[stubbornella]

How can we be certain we've maintained backwards compatibility? For teams that are using hologram out of the box? What about those that already wrote custom renderers like we did?

[gpleiss]

@stubbornella if a team has written a custom MarkdownRenderer, they'll bypass all the files added/modified as part of this PR. So they won't be able to write their own custom code renderers, but they're current code shouldn't break.

In addition, if a team doesn't have a custom_code_templates folder, Hologram will use default templates. I tested this PR out on Pivotal UI, which didn't have a custom_code_templates folder and everything worked.

[gpleiss]

I updated the documentation based on the comments from @stubbornella @pmeskers and @bebepeng

[jdcantrell]

Very solid pull request, this will definitely be handy to a lot of users.