Key Concepts

​

Projects

import { defineConfig } from "@mdcms/cli";

export default defineConfig({
  project: "marketing-site",
  serverUrl: "http://localhost:4000",
  // ...
});

​

Environments

import { defineConfig, defineType } from "@mdcms/cli";
import { z } from "zod";

const BlogPost = defineType("BlogPost", {
  directory: "content/blog",
  fields: {
    title: z.string().min(1),
    slug: z.string().min(1),
    featured: z.boolean().default(false).env("staging"),
    abTestVariant: z.string().optional().env("staging"),
  },
});

export default defineConfig({
  project: "marketing-site",
  serverUrl: "http://localhost:4000",
  contentDirectories: ["content"],
  environments: {
    production: {},
    staging: {
      extends: "production",
    },
  },
  types: [BlogPost],
});

• Isolation — Each environment has its own documents. Editing content in staging does not affect production.
• Schema overlays — Environments that extend another inherit the base schema and can add, modify, or omit fields. In the example above, staging extends production and adds featured and abTestVariant fields via the .env("staging") sugar.
• Clone & promote — You can clone all content from one environment to another, or promote a subset of documents between environments.

​

Content Types (Schema)

import { defineConfig, defineType, reference } from "@mdcms/cli";
import { z } from "zod";

const Author = defineType("Author", {
  directory: "content/authors",
  fields: {
    name: z.string().min(1),
    bio: z.string().optional(),
    website: z.string().url().optional(),
  },
});

const BlogPost = defineType("BlogPost", {
  directory: "content/blog",
  localized: true,
  fields: {
    title: z.string().min(1).max(200),
    slug: z.string().regex(/^[a-z0-9-]+$/),
    excerpt: z.string().max(500).optional(),
    author: reference("Author"),
    publishedAt: z.coerce.date(),
    tags: z.array(z.string()).default([]),
  },
});

export default defineConfig({
  project: "marketing-site",
  serverUrl: "http://localhost:4000",
  contentDirectories: ["content"],
  types: [Author, BlogPost],
});

1. Form generation — Studio renders appropriate input controls (text fields, date pickers, toggles, reference selectors) based on the Zod type of each field.
2. Validation — Both the CLI and server validate frontmatter against the schema before accepting content.
3. API behavior — The API exposes schema metadata so clients can introspect available types and their fields.

mdcms schema sync

​

Documents

---
title: Hello World
slug: hello-world
author: 11111111-1111-1111-1111-111111111111
publishedAt: 2026-01-15
tags:
  - announcements
  - getting-started
---

Welcome to our blog. This is the first post.

​

Draft/Publish Workflow

​

Localization

const Campaign = defineType("Campaign", {
  directory: "content/campaigns",
  localized: true,
  fields: {
    title: z.string().min(1),
    slug: z.string().min(1),
    summary: z.string().min(1),
  },
});

export default defineConfig({
  project: "marketing-site",
  serverUrl: "http://localhost:4000",
  contentDirectories: ["content"],
  locales: {
    default: "en",
    supported: ["en", "fr", "ja"],
    aliases: {
      "en-US": "en",
      "en-GB": "en",
    },
  },
  types: [Campaign],
});

• Each locale variant is a separate document with its own documentId, path, body, frontmatter, and version history.
• Locale variants are linked by a shared translationGroupId. This lets the Studio display a locale switcher and the API return all variants of a piece of content.
• Each variant can be at a different stage in the draft/publish workflow. Publishing the English version does not affect the French draft.
• The SDK accepts a locale parameter to query content in a specific language.

​

References

const BlogPost = defineType("BlogPost", {
  directory: "content/blog",
  fields: {
    title: z.string().min(1),
    author: reference("Author"),
    relatedPosts: z.array(reference("BlogPost")).default([]),
  },
});

• At rest, reference fields store raw UUID strings (the target document’s documentId).
• At query time, you can request resolution via the resolve parameter in the API or SDK. Resolution is shallow (one level deep) — it replaces the UUID with the target document’s data but does not recursively resolve references within the resolved document.
• Unresolved references return null in the frontmatter and include an error entry in the resolveErrors object on the response.

​

API Keys

​

Available Scopes

​

RBAC Roles

​

Scope and Constraints

• Viewer and Editor roles can be scoped to a specific project, or even a folder prefix within a project/environment. This allows fine-grained access like “editor for content/blog/ in production”.
• Admin and Owner roles are always instance-wide (global scope).
• Exactly one Owner must exist at all times. The system prevents removing or demoting the last Owner.

​

Architecture at a Glance