Choose your preferred SSG:
Choose your preferred SSG:

Choosing where to create new files

When you create a file for a collection in CloudCannon, it is saved at a path generated from a configured pattern. These patterns are called “Create Paths”. You can use these to keep your content files organized as your team members create them.

Create Paths are templates with a mixture of literal text and placeholders.

Placeholders are dynamic parts of the create path that are replaced when saving the file. They are defined between these pairs of brackets: [ ] and { }.

To change a create path:

  • Open your global configuration file.
  • Add create to a collection_config or schemas entry.

Examples

Using the slugified title from inside the new file’s front matter (or data):

cloudcannon.config.yml
collections_config:
  pages:
    create:
      path: '[relative_base_path]/{title|slugify}.md'

The example above is the default value for create if not configured.

If you are only setting the path inside create, you can set it directly as a string instead of an object:

cloudcannon.config.yml
collections_config:
  pages:
    create: '[relative_base_path]/{title|slugify}.md'

Using various data from new file’s front matter (or data):

cloudcannon.config.yml
collections_config:
  archives:
    create:
      path: '[relative_base_path]/my-folder/{date|year}-{title|slugify}.md'

Using a fixed filename and a data-dependent folder:

cloudcannon.config.yml
collections_config:
  main_pages:
    create:
      path: '[relative_base_path]/pages/{slug|deburr|slugify}/_index.md'

Defining a filename data placeholder based on date and title, then slugifies that to remove the potential leading hypens when date is unset (slugify removes leading and trailing hyphens):

cloudcannon.config.yml
collections_config:
  posts:
    create:
      extra_data:
        filename: '{date|year}-{date|month}-{date|day}-{title}'
      path: '[relative_base_path]/{filename|slugify}.[ext]'

Entries in extra_data are processed before path. They are accessible as data placeholders in path.

Overriding the default Create Path for a specific schema only:

cloudcannon.config.yml
collections_config:
  posts:
    schemas:
      default:
        path: schemas/post.md
      news:
        path: schemas/post-news.md
        create:
          path: 'news/{date|year}/{slug}[count].md'

Escaping brackets to use them in your output path:

cloudcannon.config.yml
collections_config:
  pages:
    create:
      path: '{section}/\[slug\].js'

Placeholders

Create Paths have a number of placeholders available. There are two types of placeholders: file and data placeholders.

File placeholders are always available, are surrounded with [ ] brackets, and relate to the original file path the editor was opened at:

  • [slug] is the original filename, excluding extension. Is an empty string if this results in “index”.
  • [filename] is the original filename, including extension.
  • [ext] is the last extension of the original file path.
  • [relative_path] is the full original file path, relative to the collection path.
  • [relative_base_path] is the original path excluding filename, relative to the collection path.
  • [full_slug] is an alias for [relative_base_path]/[slug].
  • [count] becomes a hyphen and number if the processed file path clashes with an existing file (e.g. file-1.md)

Data placeholders are populated from front matter or data values in the editor. They are surrounded with { } brackets. Here are some examples:

  • {title} is the title from inside the file.
  • {id} is the id from inside the file.
  • {title|lowercase} is title from inside the file, lower cased.
  • {category|slugify} is category from inside the file, slugified.
  • {tag|slugify|uppercase} is tag from inside the file, slugified, then upper cased.
  • {date|year} is date from inside the file, with the 4-digit year extracted.
  • {date|month} is date from inside the file, with the 2-digit month extracted.
  • {date|day} is date from inside the file, with the 2-digit day extracted.

Data placeholders support a number of filters. They are placed after a |, and multiple filters can be applied in sequence.

  • uppercase transforms text to uppercase.
  • lowercase transforms text to lowercase.
  • deburr converts Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removes combining diacritical marks.
  • slugify converts non-alphanumeric characters into hyphens, then collapses sequential hyphens, then removes leading/trailing and hyphens.
  • year extracts the 4-digit year extracted from a date.
  • month extracts the 2-digit month extracted from a date.
  • day extracts the 2-digit day extracted from a date.

Each data placeholder used in the Create Path adds an input to the save confirmation modal.

Changing the inputs in the save confirmation modal will also update those values in your data/front matter if those inputs are also present there.

Save confirmation screen with data placeholder inputs

Options

Create Paths have the following options available:

extra_data - Object

Adds to the available data placeholders coming from the file. Entry values follow the same format as path, and are processed sequentially before path. These values are not saved back to your file.

path - String

The raw template to be processed when creating files. Relative to the containing collection’s path.

publish_to - String

Defines a target collection when publishing. When a file is published (currently only relevant to Jekyll), the target collection’s create definition is used instead.

Unless you are changing the default Jekyll publish flow it is unlikely you need to set this.

The create entry is part of the configuration cascade, extending the number of relevant options available:

  • _inputs
  • _select_data
  • _structures
cloudcannon.config.yml
collections_config:
  posts:
    create:
      path: 'news/{date|year}/{slug}[count].md'
      _inputs:
        date:
          comment: Use the starting date here
        slug:
          comment: This is used for your filename
Was this article helpful? or Suggest an improvement >