How to set up Hologram for a Sass project?

After installing the gem, run 'hologram init' to create config files, then add /*doc */ comments to your Sass files with YAML metadata and code examples. Configure the source path to your Sass directory and include dependencies in the hologram_config.yml file.

Hologram vs Storybook for style guides?

Hologram excels at inline documentation with full customization but requires Ruby and manual styling. Storybook is JavaScript-centric, offers a rich UI out of the box, and supports interactive component development, making it better for modern frontend frameworks without Ruby dependencies.

Can I use Hologram with Vue components?

Yes, but with limitations. You can document Vue components using html_example or js_example blocks, but Hologram lacks built-in Vue-specific renderers, so you might need custom renderers for Vue single-file components or external compilation.

How to add search functionality to a Hologram style guide?

Hologram doesn't include search out of the box. You'll need to implement it manually by adding JavaScript and CSS to your documentation assets, or use third-party plugins like Cortana, which includes a search feature.

Does Hologram support live reloading?

Not natively, but you can use the Guard Hologram plugin to monitor changes and rebuild automatically, or integrate it with build tools like Grunt or Gulp that offer watch tasks for live reloading.

How to organize components hierarchically in Hologram?

Use the YAML metadata in doc comments with 'parent' and 'category' fields. Set 'parent' to another component's 'name' to nest it, and categories group components into pages, allowing for infinite nesting and logical organization.

Open-Awesome

Hologram

NOASSERTIONRuby

A Ruby gem that parses CSS/JS comments to generate customizable style guide documentation from markdown.

Visit Website GitHub

2.2k stars201 forks0 contributors

What is Hologram?

Hologram is a Ruby gem that extracts specially formatted comments from CSS, Sass, Less, Stylus, and JavaScript files to build living style guides. It separates content generation from presentation, allowing teams to maintain design systems with live, executable code examples directly embedded in the documentation.

Target Audience

Frontend developers, design system teams, and UI engineers who need to create and maintain living style guides with documentation tightly coupled to their source code.

Value Proposition

Developers choose Hologram because it keeps documentation inline with code, supports live examples that render actual components, and offers full customization of the style guide's appearance through templates, unlike many opinionated or pre-styled alternatives.

Overview

A markdown based documentation system for style guides.

Use Cases

Best For

Creating living style guides with documentation written directly in CSS, Sass, or JavaScript source files.
Embedding live, executable HTML, HAML, JavaScript, or JSX examples within style guide documentation.
Building customizable style guides where the presentation layer (HTML, CSS) is fully controlled by the team.
Organizing UI components hierarchically with parent-child relationships and categories for complex design systems.
Extending style guide support to additional languages like CoffeeScript or custom templating via custom renderers.
Displaying code examples side-by-side with their rendered output using tabular layouts for component comparison.

Not Ideal For

Teams not using Ruby or unwilling to manage Ruby gem dependencies in their project.
Projects needing a pre-styled, out-of-the-box style guide without custom CSS and HTML work.
Organizations that prefer documentation maintained in separate files rather than inline comments for cleaner code or compliance reasons.

Pros & Cons

Pros

Inline Documentation

Documentation is written directly in source code comments using /*doc */ blocks, keeping it synchronized with the code and reducing maintenance overhead.

Live Code Examples

Supports executable snippets like html_example and js_example that render interactively in the style guide, making components tangible and testable.

Full Customization

Users control the entire output with ERB templates for headers, footers, and code examples, allowing for brand-consistent and tailored style guides.

Extensible Renderers

Custom code example renderers can be added for new languages, such as CoffeeScript, by defining them in the code_example_renderers folder.

Cons

Ruby Dependency

As a Ruby gem, it requires Ruby and Bundler setup, which can be a barrier for teams using other tech stacks like Node.js or modern JavaScript frameworks.

Manual Styling Overhead

The gem only generates content; users must provide all styling, HTML structure, and assets, adding significant initial development time.

Complex Configuration

The hologram_config.yml file has numerous optional settings and requires careful path management, which can be error-prone and tedious to maintain.

Frequently Asked Questions

Related Projects

gollum

A simple, Git-powered wiki with a local frontend and support for many kinds of markup and content.

Stars14,305

Forks1,558

Last commit8 months ago

github-changelog-generator

Automatically generate change log from your tags, issues, labels and pull requests on GitHub.

Stars7,527

Forks844

Last commit4 months ago

Apipie

Ruby on Rails API documentation tool

Stars2,508

Forks454

Last commit28 days ago

rspec_api_documentation

Automatically generate API documentation from RSpec

Stars1,452

Forks368

Last commit1 year ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub