Home

Awesome

Hologram

Gem Version Build Status Code Climate Dependency Status License

Hologram is a Ruby gem that parses comments in your CSS and helps you turn them into a beautiful style guide.

There are two steps to building a great style guide:

  1. Documenting your css and javascript, and generating html examples.
  2. Styling the output of step 1.

The hologram gem itself is only concerned with step 1. This means you are free to make your style guide look however you would like. If you don't feel like going through this process yourself, you can take a look at the templates in our example repository, and use the assets defined there instead.

Installation

Add this line to your application's Gemfile:

gem 'hologram'

And then execute:

$ bundle

If you don't use bundler you can run gem install hologram.

Quick Start

hologram init

This will create a hologram_config.yml file (more on this below), starter _header.html and _footer.html files, and starter templates for rendering code examples. You can then tweak the config values and start documenting your css.

Add some documentation to one of your stylesheets:

/*doc
---
title: Alert
name: alert
category: basics
---
```html_example
    <div class='alert'>Hello</div>
```
*/

Building the documentation is simply:

hologram

Command line flags

Hologram has a couple of command line flags:

Details

There are two things you need to do to start using hologram:

  1. Create a YAML config file for your project.

  2. Go document some code!

Creating a YAML config file

Hologram needs a few configuration settings before it can begin to build your documentation for you. Once this is set up, you can execute hologram by simply running:

hologram path/to/your/config.yml or (using bundler) bundle exec hologram path/to/your/config.yml

Your config file needs to contain the following key/value pairs

Example config file
# Hologram will run from same directory where this config file resides
# All paths should be relative to there

# The directory containing the source files to parse recursively
source: ./sass

# You may alternately specify multiple directories.
# source:
#  - ./sass
#  - ./library-sass

# The directory that hologram will build to
destination: ./docs

# The assets needed to build the docs (includes header.html,
# footer.html, etc)
# 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.
dependencies:
  - ./build

# Mark which category should be the index page
# Alternatively, you may have an index.md in the source directory root
# folder instead of specifying this config.
index: basics

# To 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

Documenting your styles and components

Hologram will scan for stylesheets (.css, .scss, .sass, .less, or .styl) and javascript source files (.js) within the source directory defined in your configuration. It will look for comments that match the following:

/*doc
---
title: Buttons
name: button
category: Base CSS
---

Button styles can be applied to any element. Typically you'll want
to use either a `<button>` or an `<a>` element:

```html_example <button class="btn btnDefault">Click</button> <a
class="btn btnDefault" href="trulia.com">Trulia!</a> ```

If your button is actually a link to another page, please use the
`<a>` element, while if your button performs an action, such as
submitting a form or triggering some javascript event, then use a
`<button>` element.

*/

NB: Sass users who are using the .sass flavor of Sass should use //doc style comments with indents to create their comment blocks.

The first section of the comment is a YAML block that defines certain aspects of this documentation block (more on that in the next section). The second part is simply markdown as defined by Redcarpet.

Notice the use of html_example. This tells the markdown renderer that it should treat the example as...well...html. If your project uses haml you can also use haml_example. In that case the output will be html for the example and the code block will show the haml used to generate the html.

For components that require javascript you can use js_example. In addition to outputting the javascript in a <code> block it will also wrap it in a <script> tag for execution.

Additionally, html elements that are generated via markdown will have a class styleguide appended to them. You can use this to apply css to the styleguide itself.

Tabular layout for component documentation

If you want the code snippet next to the rendered component, instead of below, render your component horizontally by applying the html_example_table or haml_example_table modifiers to the code block.

/*doc
---
title: Buttons
name: button
category: Base CSS
---

```html_example_table
<button class="btn btnDefault">Click</button>

<a class="btn btnDefault" href="trulia.com">Trulia!</a>
```

*/

NB: Components separated by a blank line will be rendered as separate table rows.

Referencing other components

For some components, you may want to reference the documentation of another component. As an example, you may want your link components to link to the button documentation.

/*doc
---
title: Links
name: links
category: Other Category
---

...

You may want to use a button for a link.
See [the button documentation][button] for more info.

*/

You can use a reference link of the form [link description][component_name] to link to any other component in the styleguide. These links will even work if the referenced component belongs to a different category.

Document YAML section

The YAML in the documentation block can have any key/value pairs you deem important, but it specifically looks for the following keys:

For example, you might have a component with the name buttons and another component named buttonSkins. You could set the parent for the buttonSkins component to be buttons. It would then nest the buttonSkins documentation inside the buttons documentation.

Each level of nesting (components are infinitely nestable) will have a heading tag that represents its depth. In the above example buttons would have an <h1> and buttonSkins would have an <h2>.

You can see this exact example in our demo repo, and the output of this nesting in our demo style guide.

Documentation Assets

The documentation assets folder contains the html, css, js and images you'll need for making your style guide look beautiful.

Hologram doesn't care too much about what is in here as it is intended to be custom for your style guide.

Styling Your Code Examples

Hologram uses pygments.rb gem to provide syntax highlighting for code examples. One of the assets that you probably want to include in your documentation assets folder is a css file that styles the "pygmentized" code examples. We use github.css which can be found along with the css we use to style code blocks here.

Custom Code Example Renderers

By default, hologram supports the following code example types:

Let's say you want to include coffeescript examples in your styleguide. You'll need to create a custom renderer for this.

First, if none of the included templates (markup_example_template, js_example_template, etc) work for you, create new custom template files. In this example, let's say you have the templates my_custom_coffee_example_template.html.erb and my_custom_coffee_table_template.html.erb in your ./code_example_templates folder.

<!-- ./code_example_templates/my_custom_coffee_example_template.html.erb -->

<script><%= rendered_example %></script>
<div class="codeBlock coffeeExample">
  <div class="highlight">
    <pre><%= code_example %></pre>
  </div>
</div>

<!-- ./code_example_templates/my_custom_coffee_table_template.html.erb -->

<div class="codeTable">
  <table>
    <tbody>
      <% examples.each do |example| %>
        <tr>
          <td>
            <script><%= example.rendered_example %></script>
            <div class="codeBlock coffeeExample">
              <div class="highlight">
                <pre><%= example.code_example %></pre>
              </div>
            </div>
          </td>
        </tr>
      <% end %>
    </tbody>
  </table>
</div>

Next, create a custom renderer for coffeescript in the file ./code_example_renderers/coffee_renderer.rb.

# ./code_example_renderers/coffee_renderer.rb

require 'coffee-script'

Hologram::CodeExampleRenderer::Factory.define('coffee') do
  example_template 'my_custom_coffee_example_template'
  table_template 'my_custom_coffee_table_template'

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

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

Now you should be able to render coffeescript examples in your styleguide. You can render single coffeescript examples...

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

Or you can render coffeescript tables...

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

$('#myOtherDiv').click ->
  console.log 'Yeah coffee script!'

$('#yetAnotherDiv').click ->
  window.location =

Here's some details on the code example renderer factory:

Supported Preprocessors/File Types

The following preprocessors/file types are supported by Hologram:

Extensions and Plugins

Contributing

  1. Fork it
  2. Create your feature/bug fix 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

Authors

Hologram is written and maintained by August Flanagan and JD Cantrell.

Contributors

These fine people have also contributed to making hologram a better gem:

License

Hologram is licensed under the MIT License