How Keystatic organises your content

Keystatic has two concepts or structures to organise data: collections and singletons.

Those are defined in the Keystatic configuration.

You get a lot of control and flexibility with where your content gets generated, both at the collection or singleton level, and at the field level for certain field types, like images.

Path configuration

You can define where Keystatic should store collection entries and singletons via the path property in the collection/singleton top-level options.

We will go over core concepts here, but check out the Path configuration page for more details and examples.

Collections

The default path value, if not specified, will be {collection-name}/*/.

Collection paths ending with a trailing slash `/`

If the path ends with a trailing slash /, each entry will be created in its own directory named after the slug:

collection-name
└── slug
    ├── index.yaml
    └── other.mdoc

Say you create two entries in the posts collection, where the path is set to 'content/posts/*/'.

Since there is a trailing slash in the path, the generated output will look like so:

content
└── posts
    ├── my-first-post
        ├── index.yaml
        ├── other.mdoc
    └── my-second-post
        ├── index.yaml
        └── other.mdoc

Collection paths ending without a trailing slash

If the path does not end with a trailing slash, entries' index files will be created immediately inside the collection directory:

collection-name
├── slug.yaml
└── slug
    └── other.mdoc

Say you create two entries in the posts collection, where the path is set to 'content/posts/*'.

Since there is no trailing slash in the path, the generated output will look like so:

content
└── posts
    ├── my-first-post.yaml
    └── my-first-post
        └── other.mdoc
    ├── my-second-post.yaml
    └── my-second-post
        └── other.mdoc

Singletons

The path property for singletons does not contain a * wildcard.

If not specified, the default path value for singletons will be {singleton-name}/.

Singleton paths ending with a trailing slash `/`

If the path ends with a trailing slash /, the singleton's content ill be created in its own directory named after the slug:

singleton-name
└── slug
    ├── index.yaml
    └── other.mdoc

Singleton paths ending without a trailing slash

If the path does not end with a trailing slash, the singleton's index file will be created immediately inside the singleton directory:

singleton-name
├── slug.yaml
└── slug
    └── other.mdoc

Individual fields output

Right now, only images allow you to decide where content should be generated, independently of the collection/singleton level path settings.

⚡️

The reason for this is certain frameworks (like Next.js) need your images to be in a specific directory (like /public) to be easily accessible.

Instead of generating all your content inside the public directory to satisfy this requirement, Keystatic lets you define a specific path for your images only.

Here's how you define where an image gets generated for a given collection or singleton:

// In the context of a `posts` collection...
coverImage: fields.image({
  label: "Cover Image",
  directory: "public/images/posts",
}),

Regardless of where the posts entries are created, the coverImage image will be generated in public/images/posts/{post-slug}.