Open navClose nav

Sidebar Configuration

The sidebar is where you decide what content types and files you want to be able to edit in Forestry. Only admin and developers roles can access to the site sidebar settings, editors can’t.

If you import a site developed with Hugo or Jekyll, Forestry will add default sections based on those static site generators conventions. If you’re using NextJS, Gatsby, NuxtJS or Gridsome or any other static site generator, you have to define your sections manually.

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 section 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.


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, documents, 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

Sections will appear in the sidebar in the same order they are defined.


The type parameter is used by Forestry to determine how to handle the files defined in the content section.


directory is the default type for sidebar sections. A directory section will search for content files according to the path and match configuration.


A document section can be used to allow a single document to be edited. Use the path option 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.

heading,dpr_auto,f_auto,q_80,w_640/ The heading section type can be used to separate your sidebar sections into logical groups. A section of type heading only needs to specify a label for the heading.

Jekyll Pages & Jekyll Posts

The other two options are jekyll-pages and jekyll-posts, which will follow special rules for Jekyll’s page and post content types.

The jekyll-pages and 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.


The 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 directory.

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 content/.


Read our short guide on working with globs for advice on how to configure the match and exclude parameters for sidebars.

The 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 directory.

The default 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.


The exclude parameter allows you to exclude files and paths from your directory sections. exclude accepts a glob pattern just like match.

Excluding files from Jekyll pages

For a jekyll-pages section, Forestry will use the value of the exclude parameter in your Jekyll configuration.


By default, users can create both files and directories

The 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

The 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

The 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:

- type: document
  label: Help
  read_only: true

- type: heading
  label: Content

- type: jekyll-pages
  label: Pages

- type: jekyll-posts
  label: Posts

- type: directory
  path: _events
  label: Events
  - event

Multilingual Hugo Blog:


- type: heading
  label: English

- type: directory
  path: "content/posts"
  match: "**/*"
  label: Posts
  new_doc_ext: ""

- type: heading
  label: Français

- type: directory
  path: "content/posts"
  match: "**/*"
  label: Posts
  new_doc_ext: ""

Gridsome blog starter:

- type: directory
  path: content/posts
  label: Posts
  create: documents
  match: "*.md"

Gastby blog starter with data files:

- type: heading
  label: Content

- type: directory
  path: content/posts
  label: Blog Posts
  create: documents
  match: "**/*"
  new_doc_ext: md
  - blog-post

- type: document
  path: content/data/authors.yaml
  label: Author List

- type: document
  path: content/data/info.json
  label: Info Page

- type: heading
  label: General Config

- type: document
  path: config.json
  label: Site Info

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 match and 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:

- type: directory
  label: Data
  path: data
  match: "*.toml"
  new_doc_ext: ".toml"
  create: all

Access a specific data file:

- type: document
  label: Authors
  path: _data/authors.yml

Last updated on October 24, 2018