Getting started

‹ Back

Simply add the gem:

gem 'ornament', github: 'katalyst/ornament', branch: 'master'

And then run the ornament generator:

rails generate ornament

If you want to be on the bleeding-edge development version you can use the develop branch instead of master, however there may be bugs.

Required Gems

Make sure these gems to your Gemfile:

gem 'webpacker', '~> 3.5'
gem 'htmlentities', '~> 4.3.4'
gem 'simple-navigation', '~> 3.14.0'

These gems should be automatically appended to your gemfile and printed to the terminal when you generate Ornament.

Asset Precompilation

There are a few assets that Ornament will need to be precompiled, these are managed in config/initializers/ornament.rb.

Non-Koi projects

Ornament was built for Koi, but if you are using it on a non-koi project you will need to take some additional steps:

Koi comes with simple_form which Ornament has a customised initialiser for. It can be found in config/initializers/simple_form.rb. If you aren't using simple_form you will need to delete or disable this file.

Koi controllers need to include CommonControllerActions, so if you aren't using Koi you will need to disable this line from the styleguide_controller.rb:

include CommonControllerActions

Setting up your application


There are two application layouts that Ornament uses.

The first is global.html.erb which is your global template, header, footer, navigation etc.

The second is application.html.erb which is wrapped in the global template. This is where you develop your page layout logic.


Jump into the SEO partial and update the default values.

Update the names and icons in the webmanifest file.

Update the default 500.html and maintenance.html files in the public directory as required.


Ornament comes with a lot of big components made up of large JS and CSS. Depending on the size of your project you probably won't need everything included.

At the beginning of a project I typically go in to the application.scss, application.js and application_bottom.js files and disable components I likely won't be using such as object slider, tabs, tooltips etc.

Then when I start to implement these features in the application I'm developing I will bring them back in.