How to configure Orchid and scale the configuration as your site grows

See Also: Edit this page

A config file config.yml in the root of the resources directory 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 break it out into individual files in the config/ directory. Orchid merges the options in config/ with those in config.yml, which are then made available to all parts of the Orchid build. Configuration options are loaded before every build when running in "serve" mode.

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 plugin'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. This is an example of archetypes, learn more about them here.

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 config/ directory, whose filename corresponds to its options key. This process is recursive, and you can further break up those files by creating directories within config/, 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'