You can point Forestry to any folder containing Markdown, JSON, YAML or TOML files. You can not edit any other type of file.
You can also choose to point a section directly to a data file. You are free to define as many sections as you need. If you have many sections, you might prefer to define them all at once through the
.forestry/settings.yml configuration file stored in your repository.
You can define which areas (folders) of your site contain editable content files via the
sections parameter in your
.forestry/settings.yml configuration file and/or through the user interface in your site settings in the
tab given you have admin rights.
A content section in Forestry is primarily defined by the path to the folder containing content files, and a glob to match against the contents of that folder.
||Type of content||
||Text to display in Forestry menu||String||N/A|
||Path to folder from repository root (only applies to
||Glob of files to match inside of path (only applies to
||Glob pattern of files to exclude (only applies to
||Restrictions on creating new content items||
||Control Which Front Matter Templates can be used in section||Array||All templates|
||File extension for new documents created in this section||String||Value of New File Format in Forestry Settings|
||Prevent content from being edited (only applies to
Sections will appear in the sidebar in the same order they are defined.
type parameter is used by Forestry to determine how to handle the files defined in the content section.
directoryis the default type for sidebar sections. A
directorysection will search for content files according to the
documentsection can be used to allow a single document to be edited. Use the
pathoption to specify the path to the file you want to be edited. Use the read_only option to prevent this document from being edited in Forestry.
headingsection type can be used to separate your sidebar sections into logical groups. A section of type
headingonly needs to specify a label for the heading.
Jekyll Pages & Jekyll Posts
jekyll-posts section types should only be used with Jekyll sites. Additionally, you can only have one
jekyll-pages section and one
jekyll-posts section per site.
path parameter should be a path to the directory that holds this section’s content files, relative to the root of your repository. This setting only applies to sections of type
Because the path is relative to your project root, users configuring content sections for their Hugo site will want to prefix all of their paths with
Read our short guide on working with globs for advice on how to configure the
exclude parameters for sidebars.
match parameter should be a glob pattern that matches the files you want to be able to edit for this content section. Files that don’t match this pattern will be ignored. This setting only applies to sections of type
match value is
**/* which will match all files, including any files in subdirectories.
You can use the
match parameter to separate a single directory into multiple content sections, but take care to ensure that no files overlap between sections. This may cause unexpected behavior.
exclude parameter allows you to exclude files and paths from your
exclude accepts a glob pattern just like
Excluding files from Jekyll pages
jekyll-pages section, Forestry will use the value of the
exclude parameter in your Jekyll configuration.
create parameter allows you to specify whether new files can be created for the section.
all: Users can create new files and folders
documents: Users can create new files, but not new folders
none: Users can edit existing files, but cannot create new ones
Pass in an array of Front Matter Template filenames (without their extension) to limit the available Front Matter Templates when creating a new content item in this section. The templates will be shown in the dropdown in the same order they are listed here, with the first template being the default selection. If only one template is defined, the template selection dropdown will not appear when adding new content.
New Document File Extension
new_doc_ext parameter lets you specify the extension to be used for new files created in this content section. You can specify a file extension with or without the extension delimiter (the
.). The default file extension is whatever you have set as the New Page Extension in your site settings.
read_only setting only applies to
document sections. This will prevent the document from being editable in Forestry, only showing the contents of the document on the page. When used with a markdown document, the markdown will be converted to HTML and rendered appropriately. Read-only document sections are a great way to include documentation for your editors that can be accessed directly from the Forestry sidebar.
Jekyll site with pages, posts, and a custom collection:
sections: - type: document label: Help path: README.md read_only: true - type: heading label: Content - type: jekyll-pages label: Pages - type: jekyll-posts label: Posts - type: directory path: _events label: Events templates: - event
Multilingual Hugo Blog:
sections: - type: heading label: English - type: directory path: "content/posts" match: "**/*.en.md" label: Posts new_doc_ext: ".en.md" - type: heading label: Français - type: directory path: "content/posts" match: "**/*.fr.md" label: Posts new_doc_ext: ".fr.md"
Configuring Data File Sections
When using the Datafile Sections behavior, Forestry will include data files when collecting content in a sidebar section. The
directory type can be used with the
new_doc_ext options to create a section that allows to creation and management of data files similar to the behavior of markdown content.
Datafile Section Example
Access an entire directory of data files:
sections: - type: directory label: Data path: data match: "*.toml" new_doc_ext: ".toml" create: all
Access a specific data file:
sections: - type: document label: Authors path: _data/authors.yml
Caught a mistake or want to contribute to the docs? Edit this page on Github!