Choosing a Content Architecture

Before building a page section, decide whether its content should be static (edited on the page itself) or dynamic (queried from elsewhere). Making this call early, per section, keeps a template's data flow predictable.

Static: entity+fields-sidecar
Partials read entity.* properties backed by *.fields.json sidecars placed beside the consuming partial. Center of gravity: the content lives with the page that shows it. Typical signals: strong configurability is needed, or the content should scale independently across many pages. Tradeoff: content can be customized per page or reference, and sensible default values make content entry easier, but editors still have to review more options in the editor, and repeated content (the same fact shown on several pages) has to be edited in multiple places.

Dynamic: variables+list-methods
Section partials query datastore_items or other content (articles, blog posts, and similar) and render scalars pulled from the result. Schemas live on datastores/*.json or the underlying content type, not on template field sidecars. Center of gravity: the content lives once, in its own record, and is fetched wherever it's needed. Typical signals: a narrow vertical slice needs to move fast, or the same content should appear in many places without being re-entered. Tradeoff: defining content once and reusing it everywhere gives an easier editing experience with lower per-page customizability; repeated or nested queries can degrade performance, schema drift becomes a risk, and this approach doesn't eliminate the need for configuration, only defers it.

Mixing paradigms on one project
The same project typically mixes both strategies across different sections, not one or the other everywhere. Use static content (custom fields) for content that should differ across pages, such as banners, titles, calls to action, and page-level configuration. Use dynamic content (queries) for content that's reused across multiple pages, such as recent blog posts, testimonials, FAQs, or snippets.

Partials driven by input variables
It's often effective to write a partial template based on input variables rather than committing that partial to either paradigm. A consuming template can then pass it either static or dynamic content, which enables a mixed paradigm in practice — for example, dynamic content with editor fields that allow, but don't require, a static override.

Datastores work with either approach
A datastore's items can be queried dynamically (a list method with a query) or selected statically (a specific item referenced from a custom field), the same as other CMS content — choosing a datastore as the content source doesn't by itself decide static vs. dynamic.

A narrower, related choice: one field vs. a separate entity
This page is about the architecture for a whole section. A narrower, field-level version of the same question — whether one piece of content should be a fieldset, a scalar field, or its own entity or datastore item — is covered on Common Template Patterns; see its "Choosing the model" guidance when the question is about a single value rather than a whole section.

Related pattern: singleton settings
For global, single-instance settings (for example, site-wide configuration), query once in a global partial (typically included from the header), assign the result to a root-scope variable with {% assign %}, and consume it downstream. This avoids repeating the same query in every partial that needs the setting.