# forumulate.yaml in one page

A site as one file. `forumulate plan` prints the diff, `forumulate apply` carries it out and reads
every write back, `forumulate plan --check` exits 1 on drift. Full guide:
https://forumulate.com/guides/forumulate-yaml-apply

Editor validation: `$schema: https://forumulate.com/schemas/2026-12-01/forumulate-yaml.json` on the
first line, or `forumulate validate`. `${NAME}` reads the environment (`--vars-file <path>` loads a
dotenv file); an unset name stops the run and names it. Declared secrets are masked in all output.

```yaml
version: 2
org: acme
spaces:
  - slug: docs
    name: Docs
    type: DOCS
    redirects:
      - { from: /old, to: /new }          # 308 by default; status: 301 to choose
      - { from: /legacy/*, to: / }        # one trailing * carries the rest across
pages:
  - { dir: content/docs, space: docs }    # .md and .mdx; a relative dir is read from this file's folder
domains:
  - { hostname: docs.acme.com, space: docs, state: active, onUnverified: hold }
consent:
  provider: cookiemunch
  preset: { cbid: dv-xxxx }
  connect: { orgProvisioningKey: "${COOKIEMUNCH_ORG_KEY}" }
executor: { ensureKey: true }
webhooks:
  - { ref: site-build, kind: deploy_hook, url: "${DEPLOY_HOOK_URL}", events: [content.entry.published] }
```

## Top level

| Key | What |
| --- | --- |
| `version` | `2`. Required. |
| `org`, `orgName` | The organization; `orgName` lets `apply` create it. CLI only. |
| `spaces` | Spaces by `slug`; see below. |
| `pages` | `{dir, space}` for a Markdown folder, or `{space, slug, title, body}` inline. |
| `sites` | Sites and their member spaces. |
| `domains` | `hostname`, `space` or `site`, `state` (`claimed`, `verified`, `active`), `redirectTo` (301s every path), `ipAllowList`. |
| `readerAuth` | `atlas`, or `{method: atlas, instanceId}`. |
| `reader_auth` | Reader sign-in in full, org-wide or per space. |
| `readerIdentity` | `org` or `space`: how far one sign-in reaches. |
| `consent` | CMP settings; `connect` runs once, and a repeat changes nothing. |
| `executor` | Privacy executor settings; `ensureKey` mints only if none exists. |
| `privacy` | `{executor: cookiemunch}` links the rights executor. |
| `connectors` | Connectors by `providerId`. |
| `webhooks` | Endpoints and deploy hooks; give each a `ref`. |
| `tokens` | API tokens of the caller; the secret goes to `--secrets-file`. |
| `status_monitors` | Status monitors, each with its `space`. |
| `brand` | Organization brand. |
| `mail` | The organization's own mail provider (`provider`, `sender`, secrets as `${ENV}`). |
| `sources` | AI knowledge sources. |
| `translationOverrides` | Interface strings per language. |
| `orgSettings` | Organization settings by registry key. |
| `prune` | Delete what this file created earlier and no longer declares. |
| `force` | Overwrite pages, posts, releases and topics edited outside this file since the last apply (otherwise 409). |

## `spaces[]`

`id`, `slug`, `name`, `type`, `visibility`, `seed`, `preset`, `shape`, `settings`, `theme`, `redirects`,
`collections`, `categories`, `monitors`, `locales`, `description`, `seo`, `translations`, `piecePreset`,
`frontDoor`, `contactForm`, `about`, `compare`, `posts`, `authors`, `topics`, `openapi`, `homeDoc`,
`translationOverrides`, `releases`, `legalDocuments`.

## Page front matter

`title`, `slug`, `collection` or `category`, `order`, `preset`, `parentSlug`, `seoTitle`,
`seoDescription`, `canonicalUrl`, `redirectsFrom` (old paths that keep working), `draft`.

## URLs

On a space's own host a page is `https://host/<slug>`, and the index redirects to the first page. With
`basePath` it is `https://host/<basePath>/<slug>`. `plan --diff` prints each one.

## The commands around it

| Command | What |
| --- | --- |
| `forumulate init --from-site <folder>` | A first manifest from the Markdown a site has. |
| `forumulate import mdx <folder>` | What would publish as literal text, by file and line. |
| `forumulate domains records --json` | The DNS records a plan waits for, as data (`--format cloudflare`). |
| `forumulate pull <folder> --space <s>` | Studio edits back into the folder. |
| `forumulate check links <folder>` | Broken links, anchors and pictures. |
| `forumulate doctor --org <o>` | Integration health, sign-in, and every redirect rule followed to its end. |