Skip to content
MagiCMS
MagiCMS

Getting started

What is the scaffold?

The scaffold is the Astro project structure generated by magicms when you create a new site. It is the file tree under src/ (pages, layouts, components, blocks, sections, content directories, libraries, styles) plus the top-level config files (astro.config.mjs, tsconfig.json, package.json, site.config.json, magicms.project.json).

The scaffold is the boundary between what magicms manages and what you customize:

  • magicms owns the auto-generated files (see Reference § Auto-generated files) and the scaffoldVersion pin in magicms.project.json.
  • You own the content, custom blocks, custom sections, custom themes, custom layouts, and the production environment.

Most content is edited through MagiCMS, not by hand. The scaffold exists so that MagiCMS has a structured project to read from and write to at every commit.

Creating a new project

There are two supported ways to start:

  1. From the web editor: Sign in, click "New project", choose a GitHub repository, and MagiCMS generates the scaffold and commits it to a new branch. You can then clone the repository locally and run npm install and npm run dev.
  2. From a GitHub template: Use a MagiCMS template repository as a starter and connect it to the web editor when you are ready to edit.

For local folder work, open the project in the web editor using the browser File System Access API. The scaffold and content model remain the same across storage modes.

Local development

Install dependencies, sync generated files, and start the dev server:

Terminal
npm install
npm run sync      # regenerates fonts.css and inline-text-safelist.css
npm run dev       # astro dev --host (Tailwind 4, View Transitions, HMR)

Project structure

The scaffold ships a fixed file tree. Auto-generated files (marked auto-generated) are owned by magicms — edit the underlying blocks or schemas instead, and the file is regenerated.

src/
src/
├── assets/uploads/                  # CMS-uploaded images (.gitkeep)
├── blocks/<Name>/                   # Your installed blocks (PascalCase)
├── components/<Name>.astro          # Shared components (BlockRenderer / SectionRenderer auto-generated)
├── content/
│   ├── pages/<slug>.structure.json   # CMS page structure
│   ├── pages/<slug>.<lang>.json      # Translatable fields per block _id
│   ├── globals/                      # site, cookie, icons, ...
│   ├── <collection>/                 # Collection entries + .schema.json
│   ├── site.config.json              # Languages, URLs, MagiCRM / Turnstile keys
│   └── navigation.json               # Site-wide nav tree
├── lang/[lang]/                     # Multi-language route templates (only used when languages.length > 1)
├── layouts/                         # _Base.astro, Article.astro, _Documentation.astro
├── lib/                             # Server-side helpers: pages.ts, globals.ts, sitemap.ts, ...
├── pages/                           # Astro routes (default-language pages, collection detail, sitemap, robots)
├── sections/<Name>/                  # Block wrappers (e.g. Theme) + <Name>.schema.json
├── styles/styles.css                # Tailwind + daisyUI plugin
└── magicms.project.json             # scaffoldVersion + canUpgradeScaffold


# Auto-generated (do not edit by hand — edit the underlying block or schema)
# • src/components/BlockRenderer.astro
# • src/components/SectionRenderer.astro
# • src/content.config.generated.ts
# • src/lib/jsonLdRegistry.ts
# • src/lib/collectionJsonLdRegistry.ts
# • src/styles/fonts.css
# • src/styles/inline-text-safelist.css
Vi bruker cookies for å forbedre din opplevelse.