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:
- 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.
Add this line to your application's Gemfile:
And then execute:
If you don't use bundler you can run
gem install hologram.
This will create a
hologram_config.yml file (more on this below), and
also create a starter
_footer.html file for you.
You can then tweak the config values and start documenting your css.
Building the documentation is simply:
Command line flags
Hologram has a couple of command line flags:
--config- specify the config file, by default hologram looks for
--root- specify the directory to use when processing files (useful if you run hologram in a different directory than your assets. Defaults to current working directory)
There are two things you need to do to start using hologram:
Create a YAML config file for your project.
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)
Your config file needs to contain the following key/value pairs
source: relative path to your source files
destination: relative path where you want the documentation to be built
_footer.html. These are used to start and end every html page hologram generates.
_footer.html as ERB files for
each page that is generated. You can access the
blocks is a list of each documentation block on the page. Each item
in the list has a
category, and optionally a
parent. This is useful for, say, building a menu that lists each
categories is a list of all the categories found in the
Nota Bene: Filenames that begin with underscores will not be copied into the destination folder.
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.examplefor 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
<script src=>tags to the
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 # 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 # 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 documentation assets # folder instead of specifying this config. index: basics
Documenting your styles and components
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.
you can use
<code> block it will also wrap it in a
<script> tag for execution.
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.
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
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
Supported Preprocessors/File Types
The following preprocessors/file types are supported by Hologram:
- Sass (.scss, .sass)
- Less (.less)
- Stylus (.styl)
- Vanilla CSS (.css)
- Markdown (.md, .markdown)
Extensions and Plugins
- 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.
- Fork it
- Create your feature/bug fix branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request
These fine people have also contributed to making hologram a better gem:
- Rajan Agaskar
- Louis Bennett
- johny (wrote our initial tests!)
- Elana Koren
- Ken Mayer
- Roberto Ostinelli
- Nicole Sullivan