Orchid provides a powerful, yet simple and intuitive way to configure your site. It expects that large and complex sites may have lots of options set in a many-layered hierarchy, but does not sacrifice simplicity for power with smaller sites. To fully understand all that can be configured with the site config, you should refer to the Options section of the developer guide, refer to your plugins' documentation, or visit your admin panel. A basic description of site configuration and how to set it up follows.

See Also:

Edit this page

The Basics

All Orchid sites must have a config file in the root of the resources directory, called config.yml, which serves as the root of all site options. The entire site can be fully described in this one file, but if you have lots of options and want to make it easier to manage it all, you may add any options files you want to config/ (more on this below). Orchid merges the options in config/ with those in config.yml, which are then made available to all parts of the Orchid build.

In addition to config and data files, Orchid also supports setup via command-line flags. These are used for options that must be in place before we can load the config and data files, such as the directory these files reside in.

Orchid parses options before every build when running watch or serve tasks, and so support rapid changes in development and prototyping. In contrast, command-line flags are parsed once, before the main Orchid starts up, and cannot be changed during the Orchid runtime. Command-line flags are typically the kind of options that are needed to even parse config.yml or support other project-wide configuration, such as the input and output directories, or setting the default theme.

Basic Site Config

 1 theme: # (1)
 2   menu: 
 3     - type: 'readme' 
 4     - type: 'license' 
 5 wiki: # (2) 
 6   sections:
 7     - 'userManual'
 8     - 'developersGuide'
 9 services: # (3)
10   generators:
11     disabled:
12       - 'javadoc'
13       - 'posts'
15 allPages: # (4)
16   layout: single

  1. Theme options come from theme or from an object at the theme's key. When using multiple themes, you may want to use individual theme keys to configure each theme independently, but theme is generally easier to quickly try out different themes.
  2. Generator options come from an object at that Generators's key
  3. Services are all scoped under the services object, and are used to configure the behavior of the Orchid framework.
  4. In addition to the options defined in a page's FrontMatter, you may have a set of shared options that all pages, or specific sub-sets of pages should have in common. Each plugin declared these archetypal options in their own way, so consult each plugin's documentation for full site configuration.

Advanced Site Config

For larger and more complex sites, a single config.yml file will get messy very quickly. You may break up your monolithic config.yml into as many smaller files as you need, simply by adding a file in the data/ directory, whose filename corresponds to its options key. This process is recursive, and you can further break up those files by creating directories within data/, and so on. You may also specify a filename and and folder, and the two will be merged into one single options object, where the options in the file take precedence over the folder.

For example, the following YAML configs are equivalent:

Config in one single config.yml

 1 # config.yml
 2 theme:
 3   siteName: 'My Site'
 4   components:
 5     - type: pageContent
 6     - type: readme
 7     - type: license
 8   menu:
 9     - type: page
10       itemId: 'About'
11     - type: link
12       title: 'Contact'
13       url: '/contact'

Config broken into several files

# config.yml (you could even omit config.yml if desired)

# config/theme.yml
siteName: 'My Site'

# config/theme/components.yml
- type: pageContent
- type: readme
- type: license

# config/theme/menu.yml
- type: page
  itemId: 'About'
- type: link
  title: 'Contact'
  url: '/contact'

How these options get used

Now that all our options have been loaded, Orchid will start distributing them to any parts of the build that need them. The basic process goes like this:

  1. Build starts
  2. Load all options
  3. Pass appropriate options to the Theme in the following order, falling to the next if that object doesn't exist:
    • config.{theme key} (in PascalCase)
    • config.theme
    • config
  4. Pass appropriate options from the config.services.{service key} object to internal services (compiler service, render service, etc.). This is how the behavior of the full Orchid program is configured.
  5. Index each generator, passing appropriate options from the config.{generator key} (in camelCase)
  6. Generate pages each generator. If the Generator specified a theme as one of its options during the Indexing step, switch to that theme, loading that theme's options in the same manner as in step 3, before rendering the pages from that generator.