Template Docs Commerce APIs Webhooks
Get Started
Get Started

Custom Post Types

You can add custom content fields to any post type in Squarespace. This allows a developer to create posts that serve a very specific use case that is not handled by Squarespace's default post types.

This page will outline how to create a post and add it to a collection.

Creating a Custom Post Type

In your template.conf file add a key called customTypes. Here are the options (or keys) for the customTypes configuration.

title (required) A title describing the type of post. This title will show up in the CMS when you're adding a new post to the collection.

name (required) The name is a way to identify your custom post type in your template code. It is the machine name version of the title and should be formatted with camel case or hyphenation. No spaces or special characters allowed.

base (required) This is the Squarespace post type that you'd like to extend into your custom post type. The options available for base are:

  • "image"
  • "text"
  • "video"

fields (required) The data that you'd like to add to the base post type is defined here. Each data field requires a name, title, and type to be specified. The options available for fields are:

  • "text"
  • "wysiwyg"
  • "image"
  • "checkbox"
  • "gallery"

Note: While there is currently no limit to the number of fields that can exist on a custom type, there is a 50 KB limit to the amount of content. This data is stored on the customContent field on each content item.

Example

Say, for instance, you run a blog that occasionally has sponsored posts. The code below example would allow you to add a "Call to Action Link" to a custom "Sponsored Blog Post" type, and be able to access that field within the CMS.

template.conf example key:

"customTypes" : [
  {
    "title" : "Sponsored Blog Post",
    "name" : "sponsoredBlogPost",
    "base" : "text",
    "fields" : [
      {
        "name" : "ctaLink",
        "title" : "Call to Action Link",
        "type" : "text"
      }
    ]
  }
]

Adding Your Custom Post Type to a Collection

Once you've created your custom post type you need to add it to a collection, or multiple collections, on your site. Let's take the "Sponsored Blog Post" example from the above section and add it to blog collections on your site.

To do this, we need to open the blog.conf file, which is located in the collections folder. Inside the blog.conf, there is a section called "acceptTypes," which defines the post types that are accepted in that collection. Add sponsoredBlogPost to that array.

[collection].conf example key:

{
  "title" : "Blog",
  "ordering" : "chronological",
  "addText" : "Add Post",
  "acceptTypes": ["text", "sponsoredBlogPost"]
}

At this point your custom post type is ready to use. Given the example above, all you need to do is navigate to a blog in the Squarespace editor, add a custom post, and fill out your custom fields.

Templating Custom Data

The data from custom post types gets added on to a standard item. Once you add a post to your site, navigate to that page and look at it's JSON using the ?format=json-pretty search parameter. Each custom type will be an item with an additional section called "customContent." The structure will look like this (a bunch of JSON keys have been removed from the item for the sake of readability):

?format=json-pretty

"items" : [
  {
    "title" : "Sponsored Blog Post",
    "customContent" : {
      "ctaLink" : "https://www.squarespace.com/"
    }
  }
]

Now, you can output the ctaLink in your [collection].list or [collection].item template when in a repeated section items loop.