Using MagiCMS

MagiCMS is a web app that edits the JSON in an Astro project. It runs in the browser. There is no separate content database: Save writes files, and Git (or a local folder) keeps the history.

If you can work in a repo, run npm run dev, and read JSON, you have enough background. MagiCMS is the UI on top of that repo.

The data model (pages, blocks, schema) is explained on Content model. This page is the editor itself.

After sign-in you pick how MagiCMS reaches the files. The content model is the same in all three cases:

• Local folder — Chromium browsers can open a directory on your machine. Fine for solo work. Firefox and Safari are a poor fit for this mode.
• GitHub — MagiCMS reads and writes a repository you connect. Use this when the repo is the source of truth.
• Hosted project — MagiCMS talks to the MagiCMS API, which holds project membership and talks to GitHub on the server. Use this for teams and client access.

New sites: use New project, choose a starter (the public default is a classic article-width layout), and MagiCMS writes the Astro scaffold into the repo.

Which workflow to pick: Choose a workflow. Sign-in providers: Sign-in.

Typical layout:

• Sidebar — pages (and often the navigation tree), plus switches into collections, globals, media, and — if you have builder access — schemas and the block library.
• Main column — the page (or entry) you are editing: the stack of blocks and sections.
• Field panel — click a block to edit its fields. Language tabs appear when the site has more than one language.
• Preview — a live view of the Astro site when a preview URL is configured, or local preview when you run the site yourself.

A Project guide panel may show MAGICMS.md from the repo root. That file is notes for this site (URLs, who publishes), not MagiCMS product docs.

1. Open a page from the list or from Navigation.
2. Add a block or a section from the controls on the page. Reorder by dragging.
3. Select a block and fill the fields. Images go through the media picker; write alt text the schema asks for. If the field has a point of interest, click the preview so the important part stays in frame when the site scales the image with CSS.
4. If the site is multilingual, switch language and fill the translated fields. Shared structure (order of blocks, many images) stays the same unless a list is marked translatable — see Multi-language.
5. Set page title and excerpt in page meta when the layout or listings need them.
6. Save. MagiCMS writes the JSON files.

Missing a field or a layout option is usually a schema or Astro change for the developer, not something to solve by pasting HTML into a text field.

• Collections — open the collection, then an entry. Editing an entry feels like a simple page: fields from that collection’s schema. New entries get a slug (the URL segment).
• Globals — one form per global (site for name and theme, cookie banner, icons, plus any custom globals).
• Navigation — the menu tree. Labels are per language. Nesting is allowed. A parent can declare a page type so its children share extra fields (this documentation section works that way).

On GitHub and hosted projects MagiCMS does not commit straight to production.

• Save writes to the draft branch. Cloudflare Pages builds that commit. The editor preview waits until the new deployment is ready, then shows it.
• Publish merges draft into main. Production deploy (Bunny) runs from main.

There is no “Send to preview” and no preview Git branch. If a merge conflicts, MagiCMS keeps you on draft and tells you. Fix in Git or reload from a clean branch; do not assume MagiCMS rewrote history.

Local-folder projects have no branches: Save is just files on disk. You preview with npm run dev in the site.

More on branches: Branch workflow.

GitHub (and local folder) users can usually change schemas and install blocks — they are treating MagiCMS as a builder. People invited with Google are typically editors: they change page copy, entries, media and navigation, not field definitions.

Do not rename schema keys, edit generated registries, or point production URLs at random hosts unless you maintain the project. Details: Editor access.

MagiCMS will not replace Astro work. Someone still:

• Implements or restyles .astro components.
• Adds layouts and routes when the scaffold is not enough.
• Runs npm install, npm run sync and npm run dev / build.
• Wires deploy, domains and MagiCRM keys in site.config.json.

Generated files (the block registry, some TypeScript collection config, font safelists) are rewritten by MagiCMS or npm run sync. Edit the schema or the block component instead. List: Auto-generated files.

No block in the picker — install it from Block types (builder) or ask whoever owns the repo. Preview blank — check the site’s previewUrl / run Astro locally. Cannot save — check sign-in, branch, and that the path is a MagiCMS project (it needs src/content and the usual scaffold files).

First-time project checklist: Your first project. Field types when you design a schema: Schema field types.