CiceroneDocumentation

Project Generation

Cicerone can output your project as a static website.

Generate configuration

Cicerone generates your project based on a number of configuration options.

These output generation configurations are attached to content tree nodes, and as with definitions they only affect the content tree node they are defined on and the nodes below.

The configuration options are Generate Here, Collect HereDefaults, and Site Path.

Generate Here

This is the key configuration setting that actually causes Cicerone to generate and output something.

When setting Generate Here on a node, you specify the primary type of output (it can only be HTML for now) and where that output should be generated.

A node on which you set Generate Here is called a generation root. The nodes below the generation root form the generation subtree.

All partials in an HTML generation subtree are generated as HTML and assembled into one HTML output file.

As with most other things in Cicerone, a descendant of a generation root that also has Generate Here creates its own generation root and subtree. The generation subtree above stops at the lower generation root.

Note that when a partial plugin generates HTML, it also generates associated CSS and assets. While HTML is called "primary generation", CSS and assets are termed "secondary generation".

These secondary generation outputs are handled differently: via "collectors". See section below.

Collect Here

Collectors determine the output location of reusable secondary outputs generated by partials.

A reused secondary output is something about the partial that is common to all partial instances, and that should ideally be served only once. (For the time being Cicerone only supports CSS rules as reusable secondary output.)

A collector specifies the kind of thing it collects (CSS rules only for now) and where its output (the CSS file) will go in the generated site.

A collector collects outputs from nodes below it in the content tree, and each collector's output file is included in the primary generation outputs (the HTML files).

If there are multiple collectors available in the ancestry Cicerone will determine the best one based on the number of times that output will be used among the pages that will load that file.

For example...?

illustrate with article.css, section.css and site.css collectors and show how this all works

Note:There is a lot more work to do around CSS management in Cicerone!

Defaults

Specify default settings for output generation.

You might for example set that HTML files should be saved with a file extension of .htm. Every HTML file generated at or below the node will have that extension, unless of course that setting is overridden below.

You can also make it so that all asset files are generated into /assets directory, for example.

Site Path

The Site Path specifies a location within your output directory. An output file that has a relative path will be placed relative to the site path.

If a generated output is configured to have an absolute path (either in Generate Here or Defaults) the site path is ignored.

Note that Site Path configuration on a node can be relative or absolute. If it's relative, it is joined with the parent node's effective site path. For example, setting site path to design on a node that has an ancestor with site-path /sections results in an actual site path of /sections/design.

Generation Config on Partial Definition

You can set output generation configuration on partial definitions. The config will be used as if it were set on the partial root node of each instance.

You can of course override any configuration set in the partial definition by setting an alternative configuration on the root node itself.