Contentlayer's primary job is to transform your content into data that can be imported into the pages of your web project. To do that effectively, Contentlayer has to know the shape of your content — your content schema.
This is handled differently depending on whether you're working with a local source (Files) or a remote source.
With remote sources — i.e. headless CMS — the content schema is pulled in automatically from the source's API.
However, we're still experimenting with exactly how remote sources will work. As we continue to explore and add new sources, we'll update this section.
When using a local source, your schema must be explicitly defined so Contentlayer knows how to handle the local files.
You can learn more about local sources by exploring the files source guides.
Below you'll find a few concepts that are important to understand when modeling content locally.
Documents vs Nested
There are two types of objects — documents and nested (documents).
Documents are objects generated by Contentlayer, according to a document type definition. Think of a document type like a model or a table in a database. A document is then an instance of that model — i.e. the result of a database query.
Contentlayer writes documents to individual JSON files, which can then be imported into your project's pages.
Nested documents are objects that are embedded directly in a document. They are defined as nested types and are primarily used for repeatable shapes.
For example, suppose you had an SEO object that you wanted included on various models. You could define the nested document type once, and then use it within any model that requires it. The
defineNestedType API reference has more information and examples.
Just like in a database, content can be associated with other content. For example, a post document type can reference tag documents.
However, references are not currently transformed or embedded. They are passed through as a file path reference to the related object. When working with references, we recommend building utility functions that will retrieve associated data as needed.