Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/trulia/hologram

A markdown based documentation system for style guides.
https://github.com/trulia/hologram

Last synced: 2 days ago
JSON representation

A markdown based documentation system for style guides.

Awesome Lists containing this project

README 

        
# Hologram

[![Gem Version](https://img.shields.io/gem/v/hologram.svg)](https://rubygems.org/gems/hologram)

[![Build Status](https://img.shields.io/travis/trulia/hologram.svg)](https://travis-ci.org/trulia/hologram)

[![Code Climate](https://img.shields.io/codeclimate/github/trulia/hologram.svg)](https://codeclimate.com/github/trulia/hologram)

[![Dependency Status](https://img.shields.io/gemnasium/trulia/hologram.svg)](https://gemnasium.com/trulia/hologram)

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)



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](https://github.com/trulia/hologram-example/tree/master/templates)

in our [example repository](https://github.com/trulia/hologram-example),

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

        
Hello


    ```

    */



Building the documentation is simply:



``` hologram ```



### Command line flags



Hologram has a couple of command line flags:



* `-c` or `--config` - specify the config file, by default hologram

  looks for `hologram_config.yml`



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



* **source**: relative path(s) to your source files. Accepts either a

  single value or an array



* **destination**: relative path where you want the documentation to be

  built



* **documentation_assets**: The path that contains supporting assets for

  the documentation page. This typically includes html fragments

  (header/footer, etc), style guide specific CSS, javascript and any

  images. Hologram specifically looks for two files: `_header.html` and

  `_footer.html`. These are used to start and end every html page

  hologram generates.



  Hologram treats `_header.html` and `_footer.html` as ERB files for

  each page that is generated. You can access the `title`, `file_name`,

  `blocks`, and `categories`.



  `blocks` is a list of each documentation block on the page. Each item

  in the list has a `title`, `name`, `category`, and optionally a

  `parent`. This is useful for, say, building a menu that lists each

  component.



  `categories` is a list of all the categories found in the

  documentation



  **Nota Bene:** Filenames that begin with underscores will not be

  copied into the destination folder.



* **code\_example\_templates**: (optional) Hologram uses the files in this folder to

  format the code examples in the styleguide. The initializer generates 4 files:



  * `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 (see

  [the tabular layout docs](#tabular-layout-for-component-documentation)

  for more information)



  * `js_example_template.html.erb` - used for js examples



  * `jsx_example_template.html.erb` - used for jsx examples



  The html in the files will be rendered for every code example in the

  styleguide. The variable `rendered_example` represents the html

  generated by the example, while the variable `code_example` represents the

  formatted and escaped code behind the example.



  See [the documentation on custom code renderers](#custom_code_example_renderers)

  for more information,



  **Nota Bene:** If template files are missing, or this folder does not exist,

  hologram will use default templates.



* **code\_example\_renderers**: (optional) A folder that contains your custom

  code renderers. For example, if you want to have `coffee_example`s in your

  code, write a coffeescript renderer and place it in this folder. See

  [#custom_code_example_renders](below) for more inforamtion on this.



* **custom_markdown**: (optional) this is the filename of a class that

  extends RedCarpet::Render::HTML class. Use this for when you need

  additional classes or html tags for different parts of the page.  See

  [example_markdown_renderer.rb.example]

  (example_markdown_renderer.rb.example) for an example of what your

  class can look like.



* **index**: (optional) this is a category (see **Documenting your

  styles** section below) that will be used as the index.html.



* **dependencies**: a **list** of relative paths to folders containing

  any dependencies your style guide has. These folders will be copied

  over into the documentation output directory. ENSURE THE CSS/JS THAT IS

  ACTUALLY BEING DOCUMENTED IS LISTED HERE. You will also need to ensure

   that they are included on your pages. A simple way to do this is to add

   `` and `` tags to the `_header.html` file.



* **ignore_paths**: (optional) a **list** of paths to ignore. This can be a file

  name or a glob. Be sure to wrap globs in double quotes to keep yaml

  from getting too upset (ie good:"*.erb" vs bad:*.erb).



* **nav_level**: (optional) Sets the level of section navigation desired.

  `section` sets it to show sub navigation in top level sections.

  `all` sets it to show sub navigation for all sections. `all` can be a bit

  much, you'll probably want `section`.



* **custom_extensions**: (optional) Additional file extensions that will be

  included in the parse. Accepts both a single value and an array. The

  current supported file extensions are `.css`, `.scss`, `.less`, `.sass`,

  `.styl`, `.js`, `.md`, `.markdown` and `.erb`.



* **exit_on_warnings**: (optional) 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')



##### 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](http://haml.info/) 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](https://www.destroyallsoftware.com/talks/wat)

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:



* **title**: The title to display in the documents

* **category/categories**: This is the broad categories for the component, all

  components in the same category will be written to the same page. It can be set to either a string or a YAML array. If you use an array, the component will be written to both pages.

  Note: There is no need to set a category if this component has a **parent**.

* **name**: This is used for grouping components, by assigning a name, a

  component can be referenced in another component as a parent. Note that items in

  the same category are sorted alphabetically by name.

* **parent**: (Optional.) This should be the **name** of another

  component. If this is set, the current component will be displayed as

  a section within the **parent**'s documentation, but only if it specifies

  the same **category**, or allows the **category** to be inherited from its **parent**.

* **hologram**: (markdown only) To avoid conflicts with Jekyll and

  other YAML+markdown formats, Markdown (`.md`) files must include a

  `hologram: true` key/value pair in the YAML block to indicate that

  it is intended to be processed by Hologram.



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](https://github.com/trulia/hologram-example/tree/master/components/button),

and the output of this nesting [in our demo

style guide](http://trulia.github.io/hologram-example/base_css.html#Buttons).



### 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](https://github.com/tmm1/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](https://github.com/trulia/hologram-example/tree/gh-pages/static/css).



### Custom Code Example Renderers



By default, hologram supports the following code example types:



- `html_example` and `html_example_table`

- `haml_example` and `haml_example_table`

- `slim_example` and `slim_example_table`

- `js_example`

- `jsx_example`



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.



```erb

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



<script><%= rendered_example %>



  


    
<%= code_example %>


  




```



```erb





  

    

      <% examples.each do |example| %>

        

          

            <%= example.rendered_example %>

            


              


                
<%= example.code_example %>


              


            


          

        

      <% end %>

    

  



```



Next, create a custom renderer for coffeescript in the file

`./code_example_renderers/coffee_renderer.rb`.



```ruby

# ./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...



  ```coffee_example

  $('#myDiv').click ->

    alert 'Oh wow we are rendering coffee script'

  ```



Or you can render coffeescript tables...



  ```coffee_example_table

  $('#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:



* `Hologram::CodeExampleRenderer::Factory.define(example_type, &block)` -

  this is how you declare a custom renderer. `example_type` is the name of the

  renderer, and determines the example name. For example, if `example_type`

  was "foobar", in your styleguide you can create `foobar_example`s and

  `foobar_example_table`s



* `example_template` - the name of the template used to render the example,

  minus the `.html.erb` extension (e.g. "markup_example_template"). It

  should live in your **code\_example\_templates** folder



* `table_template` - (optional) the name of the template used to render examples in

  tabular form, minus the extension (e.g. "markup_table_template").



* `lexer` - (optional) a Rogue Lexer that matches the syntax of your

  example (i.e. `Rouge::Lexer.find(:haml)`, `Rouge::Lexer.find(:ruby)`).

  Here's a [complete list of possible lexers](http://rouge.jayferd.us/demo).

  If this argument is not provided, hologram will guess what the best

  one is.



* `rendered_example` - (optional) this is the set of instructions to

  "translate" your exaple so it can be rendered. I.e. for coffeescript

  to be "rendered" in the browser, you need to transform it to

  javascript (as can be seen in the block above).

  For haml, you need to transform it to html.

  If no block is provided, the code is rendered as is.



## Supported Preprocessors/File Types



The following preprocessors/file types are supported by Hologram:



- Sass (.scss, .sass)

- Less (.less)

- Stylus (.styl)

- Vanilla CSS (.css)

- Javascript (.js)

- Markdown (.md, .markdown)



## Extensions and Plugins



- [Guard Hologram](https://github.com/kmayer/guard-hologram) is a sweet

  little gem that uses guard to monitor changes to your hologram project

  and rebuilds your style guide on the fly as you make changes.

- [Grunt Hologram](https://github.com/jchild3rs/grunt-hologram/) is a sweet

  little grunt task that will generate your hologram style guide.

- [Hologram Plugin for Gulp](https://gist.github.com/jchild3rs/470be49a4bc4caf3ca8a) is a gulp task for hologram.

- [Classname Clicker](https://github.com/bigethan/hologram-addons/) is a handy

  UI addition that gives the ability to see rules that apply to a classname by

  clicking on them within hologram.

- [Cortana](https://github.com/Yago/Cortana) is a theme for hologram. It also

  includes a handy search feature.

- [Hologram Github Theme](https://github.com/wearecube/hologram-github-theme) is a Github Styleguide inspired theme for hologram.

- [Voxel Hologram](https://github.com/rishabhsrao/voxel-hologram) is a minimal theme for Hologram.

- [Acme Styleguide](https://github.com/mattrothenberg/styleguide-boilerplate) is a starter project that helps

  [Pivotal Labs Designers](https://pivotal.io/labs) build living styleguides with Sass and Hologram.



## 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](http://github.com/aflanagan) and [JD

Cantrell](http://github.com/jdcantrell).



## Contributors



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



* [Rajan Agaskar](https://github.com/ragaskar)

* Louis Bennett

* [jho406](https://github.com/jho406)

* johny (wrote our initial tests!)

* [Elana Koren](https://github.com/elanakoren)

* [Ken Mayer](https://github.com/kmayer)

* [Roberto Ostinelli](https://github.com/ostinelli)

* [Dominick Reinhold](https://github.com/d-reinhold)

* [Nicole Sullivan](https://github.com/stubbornella)

* [Mike Wilkes](https://github.com/mikezx6r)

* [Vanessa Sant'Anna](https://github.com/vsanta)

* [Geoffrey Giesemann](https://github.com/geoffwa)



## License



[Hologram is licensed under the MIT License](https://github.com/trulia/hologram/blob/master/LICENSE.txt)