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
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
$ mkdir www.example.com $ cd www.example.com $ utopia site create $ bake utopia:development
You will now have a basic template site running on
Utopia includes a redirection middleware to redirect all root-level requests to a given URI. The default being
# in config.ru 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 website 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 website 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! config.ru: 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