Home

Awesome

voxel-hologram :star:

A minimal Hologram theme based on Voxel.

Travis Gemnasium Code Climate Coveralls License

:star: Live demo

See the Voxel Hologram Example project for a live demo.

:snowboarder: Usage

Voxel Hologram has the following prerequisites:

To use Voxel Hologram, follow these steps below. Follow the :flashlight: link to refer the lines of code in Voxel Hologram Example.

  1. Install Voxel Hologram by running: :flashlight:
bower install --save-dev voxel-hologram
  1. Modify your Hologram configuration file by adding the following properties: :flashlight:
# The title is displayed in the header and in the sidebar drawer.
title: '<Your title>'

# The subtitle is displayed next to the title in the header.
subtitle: '<Your subtitle>'

# This directory contains the _header and _footer templates.
documentation_assets: '<Path to your bower_components directory>/voxel-hologram/dist'

# This directory contains the templates required to generate the different types of code examples viz. html_example, js_example, table_example, jsx_example.
code_example_templates: '<Path to your bower_components directory>/voxel-hologram/dist/_templates/code_examples_templates'

# This directory contains your custom code renderers. For example, if you want to have coffee_examples in your code, write a CoffeeScript renderer and place it in this folder.
code_example_renderers: '<Path to your bower_components directory>/voxel-hologram/dist/_templates/code_example_renderers'

# These directories contain additional images and fonts required by the Voxel theme.
dependencies:
  - '<Path to your bower_components directory>/voxel/dist/images'
  - '<Path to your bower_components directory>/voxel/dist/fonts'

# This is a list of your CSS files that you'd like to include as a link tag at the top of the page.
# This will usually be your main CSS file that you want to document.
css_include:
  - '<Path to the file that you'd like to include as a link tag>'
  - '<Another one>'
  - '<And so on...>'

# This is a list of your JS files that you'd like to include as a script tag at the bottom of the page.
js_include:
  - '<Path to the file that you'd like to include as a script tag>'
  - '<Another one>'
  - '<And so on...>'

# This directory path is used by Voxel Hologram to load its custom version of Modernizr.
bower_components_dir: '<Path to your bower_components directory>'

# This file path is your main RequireJS configuration file which is loaded in the style guide via the data-main attribute.
requirejs_main: '<Path to your main RequireJS configuration file>'

# This string is used to split the category name and the sub-category name.
namescope: ' - '

# This string is used to set the color theme for Voxel.
# Available themes: 'red', 'pink', 'purple', 'deep-purple', 'indigo', 'blue', 'light-blue', 'cyan', 'teal', 'green', 'light-green', 'lime', 'yellow', 'amber', 'orange', 'deep-orange', 'brown', 'gray', 'blue-gray'
voxel_theme: 'gray'
  1. In your RequireJS configuration, register the voxel and voxel-hologram modules: :flashlight:
// your_require_config.js
// ...
"voxel": "<Path to your bower_components directory>/voxel/dist/scripts/voxel",
"voxel-hologram": "<Path to your bower_components directory>/voxel-hologram/dist/scripts/voxel-hologram"
// ...
  1. In your main RequireJS module, initialize the voxel-hologram module: :flashlight:
// your_main_require_module.js
require([..., "voxel-hologram", ...],
function(...,  VoxelHologram, ...) {
  // ...
  VoxelHologram.create();
  // ...
});
  1. Run Hologram as usual, pointing to your modified Hologram configuration file. :flashlight:

For further reference, see the Voxel Hologram Example project.

:leaves: Additional renderers

In addition to supporting the default Hologram renderers, Voxel Hologram adds the following renderers:

:rowboat: Get started

This project depends on the following tools:

:tophat: Tip Use nvm and rvm for easy management of NodeJS and Ruby installations.

git clone git@github.com:rishabhsrao/voxel-hologram.git voxel-hologram
cd voxel-hologram
npm install
bundle install
./node_modules/.bin/bower install
./node_modules/.bin/gulp build && say awesome # Only on Mac OSX; use espeak on GNU/Linux. Windows users, sorry, no awesomeness for you!

:tophat: Tip If you have global installations of bower and gulp, then you can avoid typing the ./node_modules/.bin/ bit.

:tophat: Tip Downloading dependencies over git:// may be blocked if you are behind a firewall. The solution is to configure Git to use https:// instead of git://. Run the following to force Git to use HTTPS:

git config url.https://.insteadOf git://
# Undo using git config unset url.https://

:nut_and_bolt: Build

This project is built using Gulp.

You can run a task using ./node_modules/.bin/gulp {{task-name}}. The following build tasks are available:

:tophat: Tip It's a good idea to occasionally run:

git gc
npm prune && npm install
bower prune && bower install
bundle clean --force && bundle install

... to keep your repository lean and mean.

:scroll: License

See license.md.

The files in, code_example_renderers and code_example_templates, were inspired from the Pivotal UI project and the Cortana project.