@micacms/astro 0.6.0-rc.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micacms/astro",
-  "version": "0.6.0-rc.2",
+  "version": "0.6.0",
   "type": "module",
   "description": "Reads a Mica content repository as Astro Content Collections via the Content Layer API.",
   "license": "MIT",
@@ -44,14 +44,14 @@
   "peerDependencies": {
     "astro": "^7.0.0",
     "zod": "^4.3.6",
-    "@micacms/core": "^0.6.0-rc.2"
+    "@micacms/core": "^0.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "astro": "^7.2.2",
     "typescript": "^5.7.3",
     "zod": "^4.3.6",
-    "@micacms/core": "0.6.0-rc.2"
+    "@micacms/core": "0.6.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/setup/content-collections.md

@@ -36,49 +36,104 @@ the integrations in `astro.config.*`. For each collection, find:
 - the number of entries, and whether the ids have folders (`2024/hello`);
 - what the bodies contain: plain Markdown, raw HTML, footnotes, MDX imports and
   components, images with relative paths;
-- the pages and URLs that use the collection.
-
-## 3. Ask the user
-
-Show the inventory as a short table, and ask:
-
-1. Which collections should Mica manage? Content that only developers change,
-   such as documentation in the repository, can stay an Astro collection.
-2. The model you propose for each collection, mapped as in step 4.
-3. Every case where content cannot move without a change:
-   - MDX components in a body. Markdoc does not run them. Options: a Markdoc
-     tag that the website declares and renders, a field, or keep that
-     collection in Astro. Remove the `import` lines too, and the text that
-     refers to a component you drop.
-   - Raw HTML in a body. Markdoc does not render it. Options: Markdown (`<b>`
-     becomes `**`), a Unicode character, a Markdoc tag, or remove it. Some tags
-     have no Markdown form (`<sub>`, `<sup>`, `<kbd>`, `<mark>`). Do not change
-     HTML inside code blocks or inline code: that is text.
-   - Footnotes (`[^1]`). Markdoc shows them as text. Options: a normal
-     paragraph or a link. Remove the `[^1]` markers from the text too.
-   - Images in a body (`![](./photo.jpg)`). The rich-text editor has no images.
-     Options: a `media()` field or a `repeater()` with images, or files in
-     `public/` with absolute URLs, which Astro does not optimize.
-   - Ids with folders, or ids that are not slugs. They become flat slugs, so
-     the URL can change. Options: keep the URL with Astro `redirects`, or
-     accept the new URL.
-   - A free list of strings, such as tags. See
-     [reference.md](./reference.md#the-content-model).
-   - 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? 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.
+- the pages, components and URLs that use the collection, and the lines that
+  read each field;
+- whether the site uses Tailwind CSS 4: a stylesheet with
+  `@import "tailwindcss"`.
+
+## 3. Propose, and wait for the approval
+
+Before you write the model or change any file, show the user one proposal and
+wait for a short approval or correction. The user must know what will change
+on their website, and why, before anything changes. Write for a reader who is
+new to Mica and may know little about Astro: plain words, short sentences, no
+code. Map the fields with the table in step 4. Use this form:
+
+```markdown
+## What editors will manage
+
+**Team** (2 entries): the people on the team page.
+- Name — text, required
+- Role — text, required
+- Photo — an image, with its alt text right under it (required)
+- Editors put the people in order by dragging them.
+
+**Stays as it is:** <collections that stay in Astro, and why>
+
+## What changes in the website's files
+
+1. **The team photos' alt text moves into the photo field.** Editors then
+   write it right under the photo, and Mica does not save a photo without it.
+   In `TeamSection.astro`, two lines read the photo and its alt text in the
+   new place. Visitors see no difference.
+   Recommended. Other option: keep the alt text as its own field; then this
+   file does not change.
+2. …
+
+## What cannot move as it is
+
+- <each case from the list below, with the options>
+
+Shall I go ahead like this? You can change any point.
+```
+
+List every change to a page, a component, a layout, a style or a config file,
+one per item: what changes, in which file, whether visitors can see it
+(normally not), your recommendation, and the other option. Only what you list
+here may change later. The usual items:
+
+- **Manual order.** If a collection has a number field that only sorts it,
+  such as `order`: recommend that editors drag the entries into order. It is
+  easier, and two entries cannot get 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`: one changed line per
+  page. Other option: keep the number field, with no page change.
+- **Alt text.** If an image has its alt text in a separate field: recommend
+  the image field with alt text (`media({ accept: "image", alt: "required" })`,
+  `--map <collection>.<image>.alt=<field>`). Editors see it under the image,
+  and Mica requires it. The page then reads `entry.data.<image>.src` and
+  `.alt`, or `<Image {...entry.data.<image>} />`. Other option: keep the
+  separate field, with no page change.
+- **Dates.** A date becomes text such as `2026-01-15`. Each page that formats
+  or sorts it changes (step 7). Visitors see the same date.
+- **Bodies.** The Markdown body becomes Markdoc: `<Content />` is replaced
+  (step 7).
+- **Tailwind CSS 4.** Tailwind reads every file of the project for class
+  names, now also `src/mica.ts` and `content/`. A word in a text, such as
+  "hidden", then becomes CSS, and the CSS changes when an editor changes a
+  text. Recommend excluding both, in the stylesheet with
+  `@import "tailwindcss"`, with paths from that file:
+  `@source not "./mica.ts";` and `@source not "../content";`. Visitors see no
+  difference.
+
+What cannot move as it is, with the options to propose:
+
+- MDX components in a body. Markdoc does not run them. Options: a Markdoc tag
+  that the website declares and renders, a field, or keep that collection in
+  Astro. Remove the `import` lines too, and the text that refers to a
+  component you drop.
+- Raw HTML in a body. Markdoc does not render it. Options: Markdown (`<b>`
+  becomes `**`), a Unicode character, a Markdoc tag, or remove it. Some tags
+  have no Markdown form (`<sub>`, `<sup>`, `<kbd>`, `<mark>`). Do not change
+  HTML inside code blocks or inline code: that is text.
+- Footnotes (`[^1]`). Markdoc shows them as text. Options: a normal paragraph
+  or a link. Remove the `[^1]` markers from the text too.
+- Images in a body (`![](./photo.jpg)`). The rich-text editor has no images.
+  Options: a `media()` field or a `repeater()` with images, or files in
+  `public/` with absolute URLs, which Astro does not optimize.
+- Ids with folders, or ids that are not slugs. They become flat slugs, so the
+  URL can change. Options: keep the URL with Astro `redirects`, or accept the
+  new URL.
+- A free list of strings, such as tags. See
+  [reference.md](./reference.md#the-content-model).
+- 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).
+
+Collections that only developers change, such as documentation in the
+repository, can stay Astro collections: propose that where it fits.
+
+Wait for the answer. Change the proposal until the user agrees.
 
 ## 4. Map the schema to the model
 
@@ -158,8 +213,10 @@ from [reference.md](./reference.md#write-entries-with-a-script).
 
 ## 7. Change the pages
 
-Look at every file from the inventory: pages, layouts, components and
-endpoints such as `rss.xml.js`. See
+Make the changes that the user agreed to in step 3, and no others. If you find
+a change that the proposal did not list, describe it to the user and wait for
+an answer first. Look at every file from the inventory: pages, layouts,
+components, stylesheets and endpoints such as `rss.xml.js`. See
 [reference.md](./reference.md#render-the-content-in-astro).
 
 - `render(entry)` and `<Content />` become

package/setup/finish.md

@@ -52,33 +52,49 @@ paths if the project uses others.
 - Before a commit that changes `content/`, `npm run check` must pass.
 ```
 
+Change no other documentation, such as `README.md`, unless the user asks.
+
 ## 4. Tell the user
 
-- What you added and changed, file by file.
-- The decisions they made, and what was not converted, if anything.
-- 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/.
+Your last message is the report. Its commands are for this one time: do not
+write them into `README.md` or another file. Use this form, with the real
+files from `git status`:
+
+````markdown
+## Done
+
+Mica is set up. <one sentence on what editors can now edit>.
+
+**What changed:** <file by file, one line each: what and why, in plain words>.
+**Your decisions:** <each decision from the proposal, and the choice>.
+**Not converted:** <anything that was not converted, or "nothing">.
+**Checks:** `npm run check` and `npx astro build` pass. <how the website
+compares with the version before>.
+
+## Commit it
+
+```bash
+# 1. The setup: packages, model, collections config, agent notes.
+git add package.json package-lock.json src/mica.ts src/content.config.ts \
+  content/.mica/schema.json AGENTS.md <other setup files>
+git commit -m "Add Mica"
+# 2. The content and the page changes.
+git add -A
+git commit -m "Move the content to Mica"
+# 3. A branch that is not on the remote yet.
+git push -u origin <branch>
+```
+
+## Edit the content
+
+`npm run mica` opens the editor on this computer. A save writes files in
+`content/`; Publish commits them, and pushes a new branch the first time.
+`npm run check` checks the content (and the types, if `@astrojs/check` is
+there). On another clone, run `npm install` first. A self-hosted editor for
+other people: https://micacms.com/docs/self-hosting/.
+````
+
+- Use the project's lock file (`pnpm-lock.yaml`, `yarn.lock`) and package
+  manager.
+- For a new project without converted content, one commit is enough.
+- Run the commands only if the user asks.

package/setup/new-project.md

@@ -25,8 +25,24 @@ Ask these questions, and wait for the answers:
    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
-and fields. Change it until the user agrees.
+Then show one proposal, and wait for a short approval or correction before
+you write a file. Write for a reader who is new to Mica and may know little
+about Astro: plain words, no code.
+
+- **What editors will manage:** each collection and singleton, one line on
+  what it is, and its fields in plain words ("Title — text, required",
+  "Cover — an image, with its alt text under it").
+- **The pages:** each page you will make, with its URL and what it shows.
+- **Existing files that change:** in an empty Astro project, for example
+  `src/pages/index.astro` or a layout: what changes, and why. Nothing else
+  changes.
+- Your recommendation where there is a choice, and the other option: manual
+  order by dragging, or sorting by a field; alt text required for images that
+  carry meaning.
+
+End with: "Shall I go ahead like this? You can change any point." Change the
+proposal until the user agrees, and later make no change that it did not
+list without asking first.
 
 ## 2. Add Mica to the project