Concepts
The ideas every Meridian project rests on (sites, locales, routes, documents and publishing, modules and bundles, stable ids, users and permissions) and how they fit together.
Read this section before you model content or write templates. Each page explains one idea, shows the configuration that expresses it, and links to the full reference.
The model in one paragraph
An install is one engine, one database and one project directory. It declares its locales once and serves one or more sites; each site enables some of the locales and answers on its own domains. Content types are shared by every site unless limited, and each site’s routes decide which types have pages on it and at which URLs. Content is stored as documents: each has a draft and a published state per locale, a revision history, and a structure shared by every locale with the text translated per locale. Modules, compiled into the binary as a bundle, add types, configuration files, screens and commands to this core. Every element of the configuration carries a stable id beside its name, so renaming it keeps its data. Staff sign in to the admin and act through roles granted to their groups under a scope; members of the public realm sign in to the member portal (engine-dmo) and never hold staff permissions.
The same model as a diagram of what relates to what:
erDiagram
INSTALL ||--|{ LOCALE : declares
INSTALL ||--|{ SITE : serves
SITE }o--|{ LOCALE : enables
SITE ||--o{ ROUTE : has
CONTENT_TYPE ||--o{ ROUTE : "is routed by"
CONTENT_TYPE ||--o{ DOCUMENT : "is the type of"
SITE ||--o{ DOCUMENT : owns
DOCUMENT ||--|| SHARED_CHAIN : "has one"
DOCUMENT ||--|{ LOCALE_CHAIN : "has one per locale"
GROUP ||--o{ GRANT : "is given"
ROLE ||--o{ GRANT : "is granted by"Pages
Sites, locales and routes
One install, several sites; locales declared once and enabled per site; how a request finds its site, locale and document.
Documents, revisions and publishing
Drafts and published revisions per locale, the shared structure and per-locale chains, the workflow states, scheduling and the trash.
Modules and bundles
What core provides, what each module adds, which bundle compiles which module, and what happens when a project uses a module the binary lacks.
Stable ids
The id beside every handle: who writes it, why renames keep data, and how to recover from a copied or lost id.
Users, roles and permissions
Staff users and groups, the built-in roles, your own roles, scoped grants, and how members differ from staff.
Where each concept lives in a project
| Concept | Files | Commands |
|---|---|---|
| Locales | config/locales.yaml | engine-dmo dev locale add, engine-dmo locale |
| Sites | config/sites/<key>/site.yaml | engine-dmo dev site add, engine-dmo dev site rename |
| Routes | config/sites/<key>/routes.yaml | engine-dmo dev route add, engine-dmo describe route |
| Content types | config/schema/, config/sites/<key>/schema/ | engine-dmo dev type add, engine-dmo dev field add, engine-dmo describe type |
| Documents | The database; seed/documents/ to load some | engine-dmo content, engine-dmo seed |
| Modules | Compiled into the binary | engine-dmo version |
| Stable ids | Every configuration file, as id: | engine-dmo check --fix, engine-dmo schema plan |
| Roles and grants | config/access/roles.yaml, config/access/grants.yaml | engine-dmo user, engine-dmo access matrix |
Upgrading the engine
How to move a project to a new engine version, covering engine.version, the template contract and check --contract-report, migrations as an explicit deploy step, and the order to run things in.
Sites, locales and routes
How one Meridian install serves several sites in several locales, how locales are declared once and enabled per site, how routes give types URLs, and how a request finds its site, locale and document.