Config Files

Forestry stores the settings and configuration of the CMS for each site in a .forestry/ folder in your site’s source code. This allows developers to create default configurations that can be shared between multiple sites, and to deliver source code with Forestry CMS pre-configured.

When importing a new site, a .forestry/ folder will be added to your site’s source. Any changes made to your CMS’ configuration will be committed to your site’s source in this folder.

Site Settings

Your site settings are configured from .forestry/settings.yml.

The following is an example of settings.yml for a Hugo site.

---
upload_path: "/static/uploads/:year:/:month:/:day:"
frontmatter_file_url_template: "/uploads/:year:/:month:/:day:"
body_file_url_template: "/uploads/:year:/:month:/:day:"
new_page_extension: md
auto_deploy: false
admin_path: "/admin"
webhook_url: http://example.com/webhook
sections:

- path: content
  label: Pages
  create: all
  # Imported pages without a FMT assigned
  # will automatically use "pages"

- path: content/posts
  label: Posts
  create: all
  # use the "templates" parameter to control
  # which templates can be used for new content
  # in this section. First listed template
  # is the default option.
  templates:
  - posts

# items in content/secrets is hidden from menu
- path: content/secrets
  hidden: true

# items in content/products can be edited but not created
- path: content/products
  label: Products
  create: none
version: 0.38.1
---

Options

Admin Path admin_path: string

Allows you to configure the path where the Remote Admin will be deployed.

Upload Path upload_path: string

Allows you to configure the path where media assets are uploaded

Front Matter File URL Template frontmatter_file_url_template: string

Allows you to configure the path that is set when adding images to Front Matter Fields. Note: this value is set at upload time.

Body File URL Template body_file_url_template: string

Allows you to configure the path that is used when adding images to the body of a page. Note: this value is set at upload time.

New Page Extension new_page_extension: md|html

Allows you to configure whether new pages are created as .md or .html files.

Auto Deploy auto_deploy: boolean

Allows you to configure if publishing should be triggered when a commit is made to the source repository.

Web Hook URL webhook_url: string

Allows you to provide a web hook to be triggered when events occur in Forestry.

Version (Hugo-only) version: string This allows you to configure the version of Hugo your site uses. This is limited to the latest versions of Hugo supported by Forestry.

Content Sections sections: Array

This setting allows you to tell Forestry which parts of your site contain editable content files.

View the full Content Section documentation

Key	Description	Type	Default
`type`	Type of content	`directory`,`document`,`heading`,`jekyll-pages`,`jekyll-posts`	`directory`
`label`	Text to display in Forestry menu	String	N/A
`path`	Path to folder from repository root (only applies to `directory` type)	String	N/A
`match`	Glob of files to match inside of path (only applies to `directory` type)	String (Fileglob)	`*/`
`exclude`	Glob pattern of files to exclude (only applies to `directory` type)	String (Fileglob)	None
`create`	Restrictions on creating new content items	`all`,`none`	`all`
`templates`	Control Which Front Matter Templates can be used in section	Array	All templates
`new_doc_ext`	File extension for new documents created in this section	String	Value of New File Format in Forestry Settings
`read_only`	Prevent content from being edited (only applies to `document` type)	Boolean	`false`

Front Matter Templates

The configuration files for Front Matter Templates is found in .forestry/front_matter/templates/. Each Front Matter Template is stored as a separate file.

The following is an example of a front matter template configuration file.

homepage.yml
---
pages:
- index.md
hide_body: false
fields:
- name: title
  default: ''
  label: Title
  hidden: false
  type: text
- name: publishDate
  default: ''
  label: Date
  hidden: false
  type: datetime
- name: Categories
  default: []
  label: Categories
  hidden: false
  type: list
---

Options

Pages pages: array

Provide an array of relative page paths that you want the front matter template to apply to.

For Jekyll, provide the relative path from the project root, e.g, _posts/2017-01-01-example.md.

For Hugo, provide the relative path from your content directory, e.g, posts/2017-01-01-example.md.

Note: if a page is defined in multiple Front Matter Templates, the last Front Matter Template in alphanumerically order will be applied.

Hide Body hide_body: boolean

Toggle the display of the body editor on or off for this Front Matter Template.

Fields fields: array

The array of fields in this front matter template. They follow a standard format:

type string The field type.
name string The name or key of the field
label string The label displayed in the CMS interface
description string Help text that appears above the field
hidden boolean Toggle display of the field in the interface on or off
config object Field-specific configuration options
fields array An array of fields. For field groups and repeatable field groups only.

For a comprehensive overview of field configuration, see the field type documentation.

Removing Files

To prevent the accidental deletion of Front Matter Templates, Front Matter Templates must be removed using the interface in the CMS.

Any configuration files removed from the repo will remain in the CMS and be re-added to your site’s source on the next save or publish unless removed in Forestry.

Renaming Files

Changing the name of a Front Matter Template in Forestry will rename the config file in the repository.

Changing the file name of a config file in your repository will not rename the Front Matter Template in Forestry. Instead, a new Front Matter Template will be created with the new name, and the original template will remain in Forestry.

Adding New Files

New Front Matter Templates can be added to your repository, and will be added to the CMS upon import.

Front Matter Template config files have a strict naming convention:

File names must be all lowercase
File names must use dashes in place of spaces
File names can not contain underscores or other special characters

E.g, Example Template becomes example-template.yml

Last updated on July 25, 2018

Caught a mistake or want to contribute to the docs? Edit this page on Github!