Getting Started

Get a Madori project running and create your first content entry in under 10 steps. This guide walks you from zero to a working CMS with content you can query via GraphQL.

---

Configuration Reference

After scaffolding, your project contains madori.config.ts with these defaults:

Option	Default	Description
contentPath	./content	Where entries, globals, forms, and navigation are stored
resourcesPath	./resources	Where blueprints, fieldsets, and definitions live
usersPath	./users	Where user account files are stored
assetsPath	./public/assets	Where uploaded files are stored
cp.enabled	true	Enables the Control Panel
cp.path	/cp	URL path for the Control Panel
graphql.enabled	true	Enables the GraphQL API
graphql.path	/api/graphql	URL path for the GraphQL endpoint

You don't need to change any configuration to get started — defaults work out of the box. See the Configuration guide for customisation options.

---

Setup Steps

Prerequisites

Before you begin, make sure you have:

• Node.js 22+ — download from nodejs.org
• pnpm 11.22.0 — enable with corepack enable pnpm
• curl and tar — required by the scaffolder

1. Create a new project

Scaffold a complete MADORI project:

pnpm dlx create-madori-app@latest my-site

Choose whether to include boilerplate site content during scaffolding. The published package currently provides the scaffold; separately distributed starter-template packages are not part of this release.

This creates a my-site directory with all CMS files, blueprints, and configuration ready to go.

2. Install dependencies and start the dev server

cd my-site
pnpm install
pnpm dev

Your site is now running at http://localhost:3000.

3. Open the Control Panel

Visit http://localhost:3000/cp and sign in with the default credentials:

• Email: [email protected]
• Password: randomly generated and printed once during setup

Store the generated password securely and change it after your first login.

4. Create a collection

Collections group content that shares a structure — like blog posts, pages, or products.

1. In the Control Panel sidebar, go to Collections
2. Click Create Collection
3. Enter a title (e.g. "Blog") and a handle (e.g. blog)
4. Save the collection

This creates a definition file at resources/collections/blog.yaml.

5. Create a blueprint

Blueprints define the fields available when editing entries in a collection.

1. Go to Blueprints in the sidebar
2. Click Create Blueprint
3. Select "Collection" as the type and give it the handle blog
4. Add fields:
   • title — type: text, required
   • slug — type: slug
   • content — type: tiptap
5. Save the blueprint

Your blueprint is stored at resources/blueprints/collections/blog.yaml.

6. Create your first entry

1. Navigate to your Blog collection in the sidebar
2. Click Create Entry
3. Fill in the title, slug, and content fields
4. Click Save

Your entry is now stored as a Markdown file at content/collections/blog/your-slug.md.

7. View content on the frontend

MADORI auto-generates a GraphQL API from your blueprints. Query your new entry at http://localhost:3000/api/graphql:

{
  blogs {
    title
    slug
    content
  }
}

Use the GraphQL endpoint to render content on your frontend pages.

8. Explore your project structure

my-site/
├── content/              # Your content (Markdown + YAML)
│   └── collections/      # Collection entries
├── resources/            # Schema definitions
│   ├── blueprints/       # Field schemas
│   ├── collections/      # Collection definitions
│   ├── fieldsets/        # Reusable field groups
│   └── taxonomies/       # Taxonomy definitions
├── public/assets/        # Uploaded files
├── users/                # User accounts
├── src/                  # Application source
└── madori.config.ts      # Project configuration

All content is stored as flat files — no database required. Your content lives alongside your code and can be version-controlled with Git.

---

Common Patterns

Now that you have a working project with content, here are common next steps:

Customise your blueprint

Add more field types to capture richer content — images, dates, select options, and rich text editors. See the Field Types reference for all 18 types.

Add validation

Enforce data quality with validation rules like required, min, max, and email:

- handle: email
  field:
    type: text
    display: Email
    validate:
      - required
      - email

Organise with taxonomies

Add tags or categories to group entries. See Taxonomies for setup.

Build page layouts

Use Replicator fields with Fieldsets to let editors compose flexible page layouts from reusable blocks. The blocks field type discovers fieldsets marked with is_block: true whose handles have registered public renderers.

Generate a typed SDK

Generated projects do not bundle a CLI. Manage content with control panel, or run CLI tooling from Madori source checkout.

---

Next Steps

• Blueprints — tabs, sections, visibility conditions, and validation rules
• Collections — routes, sorting, filtering, and multiple blueprints
• Field Types — all 18 field types with configuration options
• GraphQL — auto-generated schema, queries, and client library usage
• SEO Architecture — multi-site metadata, redirects, reports, and storage boundaries
• CLI — scaffolding, migrations, code generation, and portability commands
• Assets — uploading, organising, and selecting media files
• Navigation — managing site navigation structures
• Forms — collecting submissions with validation and export