@micacms/astro 0.5.0 → 0.6.0-rc.2

package/setup/content-collections.md

@@ -13,12 +13,15 @@ entries are converted once. The website then reads them through
 - The Git working tree must be clean (`git status`). If it is not, ask the
   user to commit or stash first.
 - Ask the user whether to work on a new branch, and make it if they agree.
-- Build the website once, and copy the result to a temporary directory
-  outside the project. Step 8 compares with it.
+- Build the website once, and copy two results to a temporary directory
+  outside the project: the website, which step 8 compares with, and Astro's
+  data store, which `mica import` reads in step 6. Astro writes the store
+  again when the collections change, so this copy is the only one.
 
   ```bash
   npx astro build
   cp -r dist <temporary directory>/dist-before
+  cp node_modules/.astro/data-store.json <temporary directory>/data-store-before.json
   ```
 
 ## 2. Make an inventory
@@ -64,7 +67,16 @@ Show the inventory as a short table, and ask:
    - Headings lose their `id` and code blocks lose their highlighting, unless
      the website adds them. See
      [reference.md](./reference.md#what-markdoc-renders-differently-from-astros-markdown).
-4. Should editors put a collection in a manual order?
+4. Should editors put a collection in a manual order? If a collection has a
+   number field that only sorts it, such as `order`, give the user the choice
+   and the reason:
+   - Keep it as a `number()` field. No page changes. Editors type numbers,
+     and two entries can get the same one.
+   - Make the collection `sortable: true`. Editors drag the entries into
+     order, which is easier and cannot give two entries the same place. The
+     import turns the numbers into `_order.json` (`--order`), the field goes, and each
+     page that sorts by it sorts by `entry.data._mica.position` instead: one
+     changed line per page.
 
 Wait for the answers.
 
@@ -79,7 +91,7 @@ Wait for the answers.
 | `z.date()`, `z.coerce.date()` | `date()` (stored as `"YYYY-MM-DD"`) |
 | `z.enum([...])` | `select({ options })` |
 | `z.array(z.enum([...]))` | `select({ multiple: true, options })` |
-| `image()` | `media({ accept: "image" })` |
+| `image()` | `media({ accept: "image", alt: "required" })`, or `media({ accept: "image" })` for a decorative image |
 | `reference("authors")` | `relation({ collection: "authors" })` |
 | `z.object({...})` | `object({ fields })` |
 | `z.array(z.object({...}))` | `repeater({ fields })` |
@@ -100,51 +112,49 @@ lowerCamelCase.
 3. In `src/content.config.ts`, remove the definitions of the collections that
    Mica now manages, and add `...micaCollections(site)`. Keep the others.
 4. Run `npx astro sync`. It writes `content/.mica/schema.json`, which the
-   conversion script reads. The pages can fail now; step 7 fixes them.
+   import reads. The pages can fail now; step 7 fixes them.
 
 ## 6. Convert the entries
 
-Write a conversion script inside the project, for example
-`scripts/convert-to-mica.mjs`. Use `writeEntry` from
-[reference.md](./reference.md#write-entries-with-a-script). For each entry,
-the script:
-
-1. Reads the file and its frontmatter. For YAML, use a parser that the project
-   can already import (Astro depends on `yaml`), or install one for the
-   conversion only and remove it in step 9.
-2. Makes the slug from the id: lowercase, folders and other characters turned
-   into single hyphens. Two ids must not give the same slug.
-3. Builds `data` with every field of the model, in the stored form:
-   - a date from the text in the frontmatter, as `"YYYY-MM-DD"`. Take an ISO
-     date as it is written. Parse any other text in UTC, for example
-     `` new Date(`${text} UTC`).toISOString().slice(0, 10) ``, and compare a few
-     results with the source. Never format a local-time `Date`: in a time zone
-     east of UTC, that gives the day before.
-   - a relation as the slug of the other entry;
-   - the body as a Markdoc string, changed as the user decided in step 3;
-   - the slug field equal to the slug.
-4. Copies the image of each `image()` field to
-   `content/<collection>/<slug>/media/<file>`, and stores `media/<file>` in the
-   field. The path in the frontmatter is relative to the source entry's file.
-   Body images go where the user decided in step 3.
-5. Calls `writeEntry(collection, slug, data)`.
-6. Prints a line for each entry, and a list of everything it changed or could
-   not convert.
-
-Keep the source files. Do not delete anything in this step.
-
-Run the script, then:
+`mica import` reads the copy of the data store from step 1, where Astro keeps
+every entry after its own loader and schema. Each field of the Mica model takes
+the value with the same name. The command converts it to the stored form: a
+date to `"YYYY-MM-DD"` in UTC, a reference to a slug, an `image()` path to a
+copy in the entry's `media/` folder, and the Markdown body to the rich-text
+field `body`. It makes each slug from the entry id, and writes the files the
+way the editor does.
+
+```bash
+npx mica import --from <temporary directory>/data-store-before.json \
+  --map blog.cover.alt=coverAlt --order team=order
+```
+
+- `--map <collection>.<field>=<key>` takes a field from another key. Use it
+  when a name changed, for the alt text of an image (`blog.cover.alt=coverAlt`),
+  and for a body that goes to a rich-text field with another name
+  (`blog.content=@body`). `--map` does not reach into the rows of a repeater.
+- `--order <collection>=<field>` writes the manual order of a `sortable`
+  collection from a number field, if the user chose that in step 3.
+- Names after the options import only those collections.
+
+The command lists every key it did not import, every id that gives the same
+slug as another, and every image it did not find. Fix the model or add a
+`--map`, delete the collection's directory in `content/`, and run it again.
+Then make the changes to the bodies that the user decided in step 3 directly
+in the `.mdoc` files, and run:
 
 ```bash
 npx mica check
 ```
 
-Fix the script, not the output, until `mica check` reports 0 errors. Before
-each run, delete the converted collection's directory in `content/` (not
-`content/.mica/`), so that no file from an earlier run stays. Read every warning: "Not read" means that an
-entry or a file is lost, and a Markdoc warning means that some text does not
-render as before. If you cannot fix a warning, list it in the report with the
-reason.
+Read every warning: "Not read" means that an entry or a file is lost, and a
+Markdoc warning means that some text does not render as before. If you cannot
+fix a warning, list it in the report with the reason. Keep the source files.
+Do not delete anything in this step.
+
+If the import cannot express a conversion, for example a value that the model
+splits into two fields, write a script for that part only, with `writeEntry`
+from [reference.md](./reference.md#write-entries-with-a-script).
 
 ## 7. Change the pages
 
@@ -161,9 +171,12 @@ endpoints such as `rss.xml.js`. See
     strings gives `NaN`, and the list is then not sorted, with no error.
   - Where an API needs a `Date`, such as the RSS `pubDate`, pass
     `new Date(entry.data.pubDate)`.
-- An image was `ImageMetadata` and is now a path from the content root. Create
-  `src/lib/media.ts` from [reference.md](./reference.md#images), and use
-  `mediaImage()`.
+- An `image()` field is still `ImageMetadata` with `media({ accept: "image" })`,
+  so its pages do not change. With `alt`, the value is `{ src, alt }`: use
+  `entry.data.cover.src` where the page used `entry.data.cover`, and
+  `entry.data.cover.alt` in place of the old alt-text field, or spread it:
+  `<Image {...entry.data.cover} />`. See
+  [reference.md](./reference.md#images).
 - A reference was `{ collection, id }` and is now a slug:
   `getEntry("authors", entry.data.author)`.
 - `entry.id` is the slug. If ids had folders, update the links, and add
@@ -200,7 +213,8 @@ Ask the user before each of these:
   such as `@astrojs/mdx` when no MDX is left, and those that only the
   conversion needed. Change text in the content that describes what you
   removed.
-- Delete the conversion script, or keep it for the record.
+- Delete the temporary directory with `dist-before` and the data store copy,
+  and a conversion script if you wrote one.
 
 Then run `npx mica check` and `npx astro build` once more.
 

package/setup/finish.md

@@ -1,22 +1,39 @@
 # Finish the setup
 
-## 1. Check
+## 1. Add scripts
+
+Add two scripts to `package.json`, so that the user has short commands:
+
+```json
+"mica": "mica start",
+"check": "mica check && astro check"
+```
+
+- If the project has no `@astrojs/check`, use `"check": "mica check"`. Do not
+  install it only for this: without it, `astro check` asks to install it, and a
+  script cannot answer. Tell the user that nothing checks the types in
+  `.astro` files.
+- If the project already has a `mica` script, keep it. If it has a `check`
+  script without `mica check`, ask the user whether to add `mica check &&` in
+  front of it. If the user says no, use `npx mica check` in place of
+  `npm run check` in the steps below and in the notes.
+
+## 2. Check
 
 All three must pass:
 
 ```bash
 npx astro sync
-npx mica check     # 0 errors
+npm run check      # mica check: 0 errors; then astro check, if it is there
 npx astro build
 ```
 
-If the project has `@astrojs/check`, run `npx astro check` too. Do not install
-it only for this. Without it, nothing checks the types in `.astro` files: tell
-the user.
+If `astro check` reports errors that were there before you started, tell the
+user. Do not fix them unless the user asks.
 
 Explain each warning of `mica check` to the user, or fix it.
 
-## 2. Add notes for the next agent
+## 3. Add notes for the next agent
 
 Add this section to the project's agent instructions: `AGENTS.md`,
 `CLAUDE.md` or the file the project already uses. If `CLAUDE.md` is a link to
@@ -27,23 +44,41 @@ paths if the project uses others.
 ## Content (Mica)
 
 - The content model is `src/mica.ts`. The content is JSON and Markdoc in
-  `content/`; editors change it with `npx mica`.
-- After a change to `src/mica.ts`, run `npx astro sync` and `npx mica check`,
+  `content/`; editors change it with `npm run mica`.
+- After a change to `src/mica.ts`, run `npx astro sync` and `npm run check`,
   and commit `content/.mica/schema.json` with the change.
 - Renaming or removing a field or a collection does not move the stored
   content. Change the content files in the same commit, or ask first.
-- Before a commit that changes `content/`, `npx mica check` must report 0 errors.
+- Before a commit that changes `content/`, `npm run check` must pass.
 ```
 
-## 3. Tell the user
+## 4. Tell the user
 
 - What you added and changed, file by file.
 - The decisions they made, and what was not converted, if anything.
-- What to commit: every file that `git status` shows as new or changed,
-  including `content/.mica/schema.json`, `package.json` and the lock file. Do
-  not commit for them unless they asked.
-- How to edit: `npx mica` opens the editor on this computer. A save writes
-  files in `content/`; Publish commits them. `@micacms/editor` is a dev
+- How to commit: give the commands, and run them only if the user asks. With
+  converted content, use two commits, so that the history keeps the setup
+  apart from the content. Name the files of the first commit from
+  `git status`:
+
+  ```bash
+  # 1. The setup: packages, model, collections config, agent notes, scripts.
+  git add package.json package-lock.json src/mica.ts src/content.config.ts \
+    content/.mica/schema.json AGENTS.md
+  git commit -m "Add Mica"
+  # 2. The content and the page changes: everything else that git status shows.
+  git add -A
+  git commit -m "Move the content to Mica"
+  ```
+
+  Use the project's lock file (`pnpm-lock.yaml`, `yarn.lock`). For a new
+  project without converted content, one commit is enough.
+- How to publish the branch: on a branch that is not on the remote yet,
+  `git push -u origin <branch>`. The editor's Publish does this too, the first
+  time.
+- How to edit: `npm run mica` opens the editor on this computer. A save writes
+  files in `content/`; Publish commits them. `npm run check` checks the content
+  (and the types, if `@astrojs/check` is there). `@micacms/editor` is a dev
   dependency, so on another clone, run `npm install` first.
 - That a self-hosted editor for other people is described at
   https://micacms.com/docs/self-hosting/.

package/setup/new-project.md

@@ -17,8 +17,12 @@ Ask these questions, and wait for the answers:
 3. Do entries refer to other entries? For example, an article has an author
    from the team.
 4. Should editors put a collection in a manual order?
-5. Do images need alt text that editors write? A media field has none, so
-   each image that carries meaning needs a `text()` field beside it.
+5. Which images carry meaning, and which are decorative? An image that
+   carries meaning gets `media({ accept: "image", alt: "required" })`, so that
+   editors write its alt text. A decorative image gets
+   `media({ accept: "image" })`. `accept: "image"` makes the field an Astro
+   image on the pages; without it, the field is a path, for a PDF or another
+   file.
 6. Do they want example content, so that the pages show something at once?
 
 Suggest a model from the answers, as a short list of collections, singletons

package/setup/reference.md

@@ -9,7 +9,9 @@ The guides link here. Read the section that a step names.
 | `npx mica init` | Writes a starter `src/mica.ts` and `src/content.config.ts`. Never overwrites a file |
 | `npx astro sync` | Runs the Mica loaders, which write the model to `content/.mica/schema.json` |
 | `npx mica check` | Checks every entry against `content/.mica/schema.json`. Exit code 1 on an error |
-| `npx mica` | Opens the editor in the browser. Only for the user; do not run it yourself |
+| `npx mica import` | Moves Astro collections into Mica, from Astro's data store. See [content-collections.md](./content-collections.md#6-convert-the-entries) |
+| `npx mica migrate-layout` | Moves entries into the layout of the model, after the first or the last rich-text or media field of a collection was added or removed |
+| `npx mica start` | Opens the editor in the browser. Only for the user; do not run it yourself |
 
 `mica check` reads the model from `content/.mica/schema.json`. After every
 change to `src/mica.ts`, run `npx astro sync` before `npx mica check`.
@@ -61,7 +63,7 @@ in the entry list), `readonly`, `hidden`, `group`, `width` (`"full"`, `"half"`,
 
 | Field | Stored as | Other options |
 | --- | --- | --- |
-| `text()` | string | `minLength`, `maxLength`, `pattern`, `placeholder`, `default` |
+| `text()` | string | `minLength`, `maxLength`, `pattern` (must match the whole value), `placeholder`, `default` |
 | `textarea()` | string | `minLength`, `maxLength`, `rows`, `placeholder`, `default` |
 | `richText()` | Markdoc in its own `.mdoc` file | `toolbar`, `maxLength`, `default` |
 | `number()` | number | `min`, `max`, `step`, `integer`, `unit`, `default` |
@@ -74,7 +76,7 @@ in the entry list), `readonly`, `hidden`, `group`, `width` (`"full"`, `"half"`,
 | `object()` | object | `fields` (required), `collapsible`, `collapsed` |
 | `repeater()` | array of objects | `fields` (required), `min`, `max`, `itemLabel`, `addLabel` |
 | `relation()` | the slug of an entry | `collection` (required), `multiple` |
-| `media()` | a file path | `accept: "image" \| "document" \| "any"`, `multiple`, `max` |
+| `media()` | a file path, or `{ path, alt }` with `alt` | `accept: "image" \| "document" \| "any"`, `multiple`, `max`, `alt: "required" \| "optional"` |
 | `color()` | `"#rrggbb"` | `presets`, `default` |
 | `coordinates()` | `{ "lat": 47.37, "lng": 8.54 }` | `defaultCenter`, `defaultZoom` |
 
@@ -152,12 +154,13 @@ export async function writeOrder(collection, slugs) {
   await writeFile(join(ROOT, collection, "_order.json"), `${JSON.stringify(slugs, null, 2)}\n`);
 }
 
-// Example: `data` has every field, rich text as a Markdoc string, media as `media/<file>`.
+// Example: `data` has every field, rich text as a Markdoc string, and media as
+// `media/<file>`, or `{ path, alt }` for a `media({ alt })` field.
 // await writeEntry("news", "hello-world", {
 //   title: "Hello, world",
 //   slug: "hello-world",
 //   publishedOn: "2026-01-15",
-//   cover: "media/cover.jpg",
+//   cover: { path: "media/cover.jpg", alt: "The team at the opening" },
 //   body: "The first article.",
 // });
 ```
@@ -206,41 +209,24 @@ const settings = await getEntry("settings", "settings");
 
 ### Images
 
-On disk, a media field holds `media/cover.jpg`. In `entry.data`, the loader
-gives the path from the content root: `news/hello-world/media/cover.jpg`. Astro can only optimize an image that the
-build imports, so collect the images with `import.meta.glob`:
-
-```ts
-// src/lib/media.ts — the glob path is relative to this file
-import type { ImageMetadata } from "astro";
-
-const images = import.meta.glob<{ default: ImageMetadata }>(
-  "../../content/**/*.{jpeg,jpg,png,webp,avif,gif}",
-  { eager: true },
-);
-
-/** The image for a Mica media path, or undefined when the file is not there. */
-export function mediaImage(path: string | null | undefined): ImageMetadata | undefined {
-  return path ? images[`../../content/${path}`]?.default : undefined;
-}
-```
+A `media({ accept: "image" })` field reaches Astro as an image that Astro
+optimizes, the same as `image()` in an Astro collection: `ImageMetadata`. With
+`alt`, it is `{ src, alt }`. No helper is needed:
 
 ```astro
 ---
 import { Image } from "astro:assets";
-import { mediaImage } from "../../lib/media";
-const cover = mediaImage(article.data.cover);
+const { cover } = article.data; // media({ accept: "image", alt: "required" })
 ---
-{cover && <Image src={cover} alt={article.data.title} />}
+{cover && <Image {...cover} />}
 ```
 
-A `media({ multiple: true })` field is an array of paths:
-`project.data.gallery.map(mediaImage)`.
-
-A media field has no alt text. Add a `text()` field for it where the image
-carries meaning. For documents such as PDF files, use
-`import.meta.glob("../../content/**/*.pdf", { query: "?url", import: "default", eager: true })`
-and link to the URL.
+- Without `alt`, the field is the image itself: `<Image src={logo} alt="" />`.
+- A `media({ accept: "image", multiple: true })` field is an array of them.
+- On disk, the field still holds `media/cover.jpg`, or `{ path, alt }`.
+- A `media()` without `accept: "image"`, for example a PDF, is a path from the
+  content root: `news/hello-world/media/plan.pdf`. To link to it, use
+  `import.meta.glob("../../content/**/*.pdf", { query: "?url", import: "default", eager: true })`.
 
 ### What Markdoc renders differently from Astro's Markdown
 

package/src/images.ts

@@ -0,0 +1,49 @@
+/**
+ * Image fields reach Astro through its own `image()`, which resolves a path
+ * against the entry's file, optimizes the image and gives `ImageMetadata`. A
+ * site then needs no helper: `<Image {...entry.data.cover} />`.
+ */
+
+import { posix } from "node:path";
+
+import type { FieldMap } from "@micacms/core";
+
+/**
+ * Rewrites the paths of `media({ accept: "image" })` fields, which the reader
+ * gives from the content root, to paths from the entry's data file.
+ */
+export function imagePathsFromEntry(
+  fields: FieldMap,
+  data: Record<string, unknown>,
+  dataFile: string,
+): Record<string, unknown> {
+  const from = posix.dirname(dataFile);
+  const relative = (path: unknown): unknown => {
+    if (typeof path !== "string" || path === "") return path;
+    const result = posix.relative(from, path);
+    return result.startsWith(".") ? result : `./${result}`;
+  };
+  const one = (value: unknown): unknown =>
+    isRecord(value) ? { ...value, path: relative(value["path"]) } : relative(value);
+
+  const visit = (map: FieldMap, record: Record<string, unknown>): Record<string, unknown> => {
+    const result = { ...record };
+    for (const [key, field] of Object.entries(map)) {
+      const value = record[key];
+      if (field.kind === "media" && field.accept === "image") {
+        result[key] = Array.isArray(value) ? value.map(one) : one(value);
+      } else if (field.kind === "object" && isRecord(value)) {
+        result[key] = visit(field.fields, value);
+      } else if (field.kind === "repeater" && Array.isArray(value)) {
+        result[key] = value.map((row) => (isRecord(row) ? visit(field.fields, row) : row));
+      }
+    }
+    return result;
+  };
+
+  return visit(fields, data);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}