Hologram is a Rails gem made by Trulia, it helps to create a styleguide for your project based on comments you leave in your .css/.scss/.less/.styl/etc.
Why do I need styleguides on my projects?
In every project you should have style trends and problems that you always solve with the same flow or using the same conventions. Something important for a cool UX is to keep the same patterns at the moment of resolving similar problems.
How does Hologram work?
Hologram makes this easy by extending Markdown code blocks that can be marked as examples. The block will then be rendered twice: Once as the actual HTML output and once again as HTML code.
Why it’s a good idea to use Hologram for making your own styleguide:
It lets you take control of your styleguide super easily.
No default styles, you can use your own.
Super flexible way to define documentation.
Once the doc styles are defined it is really easy to keep adding stuff to it.
Cool, I like it, how do I start?
After adding Hologram as a dependency on your project you can start using the CLI by running hologram or (using bundler) bundle exec hologram.
Now you need to have a configuration file, through this file you’re going to declare where to start searching for styles, where to save the compiled docs, and basically all the things you can configure about Hologram (which we’re going to specify better in a moment).
To create this configuration file, run hologram init.
Ok, so, let’s see what happened here...
This command created a hologram_config.yml file, this is the file you’re going to use to configure Hologram. You can always rename this file or move it and then run hologram by giving it a param with its current path, by default it will look for a hologram_config.yml where you are.
It also created a doc_assets folder, here you’ll find a _header.html and a _footer.html. you can change both these files to give some life to your styleguide, for instance editing the head and add some css to this black and white thing ;). All the files for the doc should be under this directory, feel free to structure it as you want.
Now we also have the docs directory, by default here is where you’ll have your doc, you can change this location by changing the destination prop in your config file.
Now, let’s start by adding some stuff to our documentation!
Here is an example documentation block from the official documentation.
We use Hologram here at VAIRIX, why don’t you take a look at it? ;)