Fields

Import the builders from @micacms/core. Each builder gives plain data, so the editor can read the model from .mica/schema.json.

Options of every field

The build stops on an option that is not in these tables, for example a typo. A field with an option from a newer @micacms/astro is read-only in an older Mica until you upgrade it.

The builders

Defaults and empty values

A default fills the field of a new entry, and of a singleton that has no file yet. It never fills a value that is missing in a stored entry: such a value is empty, null, false or [], and your templates must handle it. So a changed default does not change the stored entries, and a cleared field stays cleared.

Values that the model does not have

A save keeps a key in index.json and a .mdoc file that the model does not declare, for example content for a field that a newer model adds. Your templates do not get them, and npx mica check warns about them. To delete them, see Change the model. A key in a list row without _key is not kept, because such a row has no identity when the order changes.

The ID of a collection

The first id() among the fields of a collection is the entry's ID. It is also the name of the entry's folder, so it is never empty, and it cannot be localized. A second id() among the same fields stops the build. An id() in an object or in a singleton, or a localized id(), is an ordinary value, for example one page name for each language. A localized id() among the fields of a collection must be unique in each locale: npx mica check and Publish report a value that another entry has.

Where an entry is stored

Each entry is a folder <id>/ with index.json, the .mdoc files and the entry's media, and each singleton is a folder <name>/ with the same files. See Content model.

Each rich-text field has its own .mdoc file, named by the field's path: body.mdoc, seo.intro.mdoc, and body.de.mdoc for a localized field. In a repeater(), each row with rich text has a key, _key, in index.json, and the file names the row by its key: sections.k3f9a2.body.mdoc. Then a new order of the rows changes only index.json. Mica writes the key; do not change it. Your templates do not get it.

Collections and singletons

import { collection, defineSite, singleton, id, text } from "@micacms/core";

export const site = defineSite({
  root: "./content",
  collections: {
    news: collection({ label: "News", url: "/news/{id}", fields: { title: text({ required: true }), id: id({ from: "title" }) } }),
  },
  singletons: {
    settings: singleton({ label: "Website", fields: { tagline: text() } }),
  },
});

singleton() takes label, description, fields and url (its page, such as /about or /{locale}/about, without {id}). defineSite() takes root, label, collections, singletons and references, and for a multilingual site locales, defaultLocale (default: the first locale), fallback and prefixDefaultLocale (default: false, as in Astro: the default locale's address has no prefix). See Localization.

Reference sets

referenceSet({ label, file, id, title }) declares data of the website that Mica never edits, and that a relation() can point to. It goes in references of defineSite(), under the name of the website's own Astro collection for that file. file is the file from the project root, id the key of an item's id (default id), and title the key that the editor shows. See Reference data.