Getting Started

This guide explains how to set up a utopia website for local development and deployment.


Utopia is built on Ruby and Rack. Therefore, Ruby (suggested 2.0+) should be installed and working. Then, to install utopia and all required dependencies, run:

$ gem install utopia

Atom Integration

Utopia uses Trenni for templates and it has a syntax slightly different from ERB. However, there is a package for Atom which provides accurate syntax highlighting.

Your First Page

To setup the default site, create a directory (typically the hostname of the site you want to create) and use the utopia command:

$ mkdir
$ cd
$ utopia site create
$ bake utopia:development

You will now have a basic template site running on https://localhost:9292.

Welcome Page

Utopia includes a redirection middleware to redirect all root-level requests to a given URI. The default being /welcome/index:

# in

use Utopia::Redirection::Rewrite,
	'/' => '/welcome/index'

The content for this page is stored in pages/welcome/index.xnode. The format of this page is a subset of HTML5 - open and close tags are strictly enforced.

There are several special tags which are used for creating modular content. The most common one is the outer <content:page> tag. Utopia uses the name page to lookup the file-system hierarchy. First, it looks for /welcome/_page.xnode, and then it looks for /_page.xnode which it finds. This page template includes a special <utopia:content/> tag which is replaced with the inner body of the <content:page> tag. This recursive lookup is the heart of Utopia.


Utopia websites include a default set of tests using rspec. These specs can test against the actual running website.

$ rspec

1 samples: 1x 200. 1170.96 requests per second. S/D: 0.000µs.
  should be responsive

Finished in 0.61764 seconds (files took 0.64705 seconds to load)
1 example, 0 failures

The website test will spider all pages on your site and report any broken links as failures.


The covered gem is used for providing source code coverage information.

$ COVERAGE=BriefSummary rspec

1 samples: 1x 200. 67.53 requests per second. S/D: 0.000µs.
  should be responsive

* 5 files checked; 33/46 lines executed; 71.74% covered.

Least Coverage:
pages/_page.xnode: 6 lines not executed! 4 lines not executed!
pages/welcome/index.xnode: 2 lines not executed!
pages/_heading.xnode: 1 lines not executed!

Finished in 1.82 seconds (files took 0.51845 seconds to load)
1 example, 0 failures