Set the path for new files

Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.

Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.

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

copied

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

cloudcannon.config.json

copied

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

cloudcannon.config.cjs

copied

module.exports = {
  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.yaml

copied

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

cloudcannon.config.json

copied

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

cloudcannon.config.cjs

copied

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

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

cloudcannon.config.yaml

copied

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

cloudcannon.config.json

copied

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

cloudcannon.config.cjs

copied

module.exports = {
  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.yaml

copied

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

cloudcannon.config.json

copied

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

cloudcannon.config.cjs

copied

module.exports = {
  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.yaml

copied

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

cloudcannon.config.json

copied

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

cloudcannon.config.cjs

copied

module.exports = {
  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.yaml

copied

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

cloudcannon.config.json

copied

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

cloudcannon.config.cjs

copied

module.exports = {
  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.yaml

copied

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

cloudcannon.config.json

copied

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

cloudcannon.config.cjs

copied

module.exports = {
  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.yaml

copied

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

cloudcannon.config.json

copied

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

cloudcannon.config.cjs

copied

module.exports = {
  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"
          }
        }
      }
    }
  }
};