Set the path for 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.

To change a create path:

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

Examples#

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

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

{
  "collections_config": {
    "pages": {
      "create": {
        "path": "[relative_base_path]/{title|slugify}.md"
      }
    }
  }
}

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

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

{
  "collections_config": {
    "pages": {
      "create": "[relative_base_path]/{title|slugify}.md"
    }
  }
}

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

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

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

Using a fixed filename and a data-dependent folder:

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

{
  "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):

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

{
  "collections_config": {
    "posts": {
      "create": {
        "extra_data": {
          "filename": "{date|year}-{date|month}-{date|day}-{title}"
        },
        "path": "[relative_base_path]/{filename|slugify}.[ext]"
      }
    }
  }
}

Overriding the default Create Path for a specific schema only:

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

{
  "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:

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

{
  "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.

Options#

Create Paths have the following options available:

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

{
  "collections_config": {
    "blog": {
      "create": {
        "extra_data": {
          "filename": "{date|year}-{date|month}-{date|day}-{title}"
        },
        "path": "[relative_base_path]/{filename|slugify}.[ext]"
      }
    }
  }
}

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

{
  "collections_config": {
    "blog": {
      "create": {
        "extra_data": {
          "filename": "{date|year}-{date|month}-{date|day}-{title}"
        },
        "path": "[relative_base_path]/{filename|slugify}.[ext]"
      }
    }
  }
}

collections_config:
  blog:
    create:
      path: >-
        [relative_base_path]/{date|year}-{date|month}-{date|day}-{title|slugify}.[ext]

{
  "collections_config": {
    "blog": {
      "create": {
        "path": "[relative_base_path]/{date|year}-{date|month}-{date|day}-{title|slugify}.[ext]"
      }
    }
  }
}

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

• _inputs
• _select_data
• _structures

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

{
  "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"
          }
        }
      }
    }
  }
}