Globals

Globals are site-wide data sets that exist outside of collections. Use them for content that applies across the entire site — site settings, footer content, social media links, company information, or any data that isn't tied to a specific collection entry.

Unlike collection entries (which have multiple instances), each global has exactly one instance. Editors access globals directly from the Control Panel sidebar.

---

Configuration Reference

Global Definition

Global definitions live at resources/globals/{handle}.yaml. The definition tells Madori which blueprint provides the editing fields.

Property	Type	Required	Default	Description
title	string	Yes	—	Display name shown in the Control Panel sidebar
blueprint	string	Yes	—	Handle of the blueprint that defines the field schema

Example definition:

# resources/globals/site-settings.yaml
title: Site Settings
blueprint: site-settings

Global Blueprint

Global blueprints follow the same structure as collection blueprints and live at resources/blueprints/globals/{handle}.yaml:

# resources/blueprints/globals/site-settings.yaml
tabs:
  main:
    display: General
    fields:
      - handle: site_name
        field:
          type: text
          display: Site Name
          required: true

      - handle: tagline
        field:
          type: text
          display: Tagline

      - handle: logo
        field:
          type: asset
          display: Logo
          options:
            max_files: 1

All field types and validation rules are supported in global blueprints.

Data Storage

Global data is stored as YAML at content/globals/{handle}.yaml:

# content/globals/site-settings.yaml
site_name: My Awesome Site
tagline: Built with Madori
logo: /assets/logo.svg

API Endpoints

Method	Endpoint	Description
GET	/api/globals	List all globals
GET	/api/globals/{handle}	Get a global's data
PUT	/api/globals/{handle}	Update a global's data

File Structure

resources/
├── globals/
│   ├── site-settings.yaml     # Definition
│   └── footer.yaml            # Definition
├── blueprints/globals/
│   ├── site-settings.yaml     # Blueprint (fields)
│   └── footer.yaml            # Blueprint (fields)
content/
└── globals/
    ├── site-settings.yaml     # Data
    └── footer.yaml            # Data

---

Usage Examples

Creating a Global

Step 1: Create the definition:

# resources/globals/site-settings.yaml
title: Site Settings
blueprint: site-settings

Step 2: Create the blueprint:

# resources/blueprints/globals/site-settings.yaml
tabs:
  general:
    display: General
    fields:
      - handle: site_name
        field:
          type: text
          display: Site Name
          required: true
          validate:
            - required
            - max:100

      - handle: tagline
        field:
          type: text
          display: Tagline
          validate:
            - max:200

      - handle: logo
        field:
          type: asset
          display: Logo
          options:
            max_files: 1

  social:
    display: Social Links
    fields:
      - handle: twitter_url
        field:
          type: text
          display: Twitter/X URL
          validate:
            - url

      - handle: github_url
        field:
          type: text
          display: GitHub URL
          validate:
            - url

Step 3: Edit in the Control Panel by navigating to Globals → Site Settings.

Querying via GraphQL

{
  global(handle: "site-settings") {
    data
  }
}

The data field returns the raw YAML content as a JSON object.

Querying via REST API

# Get all globals
curl http://localhost:3000/api/globals

# Get specific global
curl http://localhost:3000/api/globals/site-settings

# Update a global
curl -X PUT http://localhost:3000/api/globals/site-settings \
  -H "Content-Type: application/json" \
  -d '{"site_name": "Updated Name", "tagline": "New tagline"}'

Using Global Data in Next.js

async function getSiteSettings() {
  const res = await fetch(`${process.env.SITE_URL}/api/globals/site-settings`)
  const json = await res.json()
  return json.data
}

export default async function Layout({ children }) {
  const settings = await getSiteSettings()

  return (
    <html>
      <head>
        <title>{settings.site_name}</title>
      </head>
      <body>
        <header>
          {settings.logo && <img src={settings.logo} alt={settings.site_name} />}
          <h1>{settings.site_name}</h1>
          <p>{settings.tagline}</p>
        </header>
        {children}
      </body>
    </html>
  )
}

---

Common Patterns

Site Settings Global

The most common global — contains site-wide metadata:

# resources/blueprints/globals/site-settings.yaml
tabs:
  general:
    display: General
    fields:
      - handle: site_name
        field:
          type: text
          display: Site Name
          required: true

      - handle: tagline
        field:
          type: text
          display: Tagline

      - handle: logo
        field:
          type: asset
          display: Logo
          options:
            max_files: 1

      - handle: favicon
        field:
          type: asset
          display: Favicon
          options:
            max_files: 1

Footer Content Global

Editable footer content without touching templates:

# resources/blueprints/globals/footer.yaml
tabs:
  main:
    display: Footer
    fields:
      - handle: copyright_text
        field:
          type: text
          display: Copyright Text
          default: "© 2026 My Company"

      - handle: footer_links
        field:
          type: replicator
          display: Footer Links
          options:
            sets:
              - footer_link

      - handle: show_newsletter
        field:
          type: toggle
          display: Show Newsletter Signup
          default: true

Social Media Links

Centralise social links for use in headers, footers, and metadata:

# resources/blueprints/globals/social.yaml
tabs:
  main:
    display: Social Profiles
    fields:
      - handle: twitter
        field:
          type: text
          display: Twitter/X
          validate:
            - url

      - handle: github
        field:
          type: text
          display: GitHub
          validate:
            - url

      - handle: linkedin
        field:
          type: text
          display: LinkedIn
          validate:
            - url

      - handle: youtube
        field:
          type: text
          display: YouTube
          validate:
            - url

Multiple Globals for Separation of Concerns

Split site configuration into logical groups rather than one large global:

resources/globals/
├── site-settings.yaml   # Core site identity
├── footer.yaml          # Footer-specific content
├── social.yaml          # Social media links
├── seo-defaults.yaml    # Default meta tags
└── analytics.yaml       # Tracking configuration

Each appears as a separate item in the Control Panel sidebar, making it easy for editors to find what they need.