DocsAuthoring guide

Slide shorthand

Two shortcuts at the slide root: list several content payloads and let the renderer arrange them, or name a region key to pin each payload in place.

Which to use

Composition matters, exact placement does not: use implicit blocks (or blocks directly).
Exact placement matters: use promoted regions.
For a registered layout, set each block’s region to a region name of that layout; see layouts and pins. Promoted region keys are a separate 3×3 placement shorthand.

Implicit blocks

OPF supports blocks for slides that contain multiple content payloads but do not need explicit placement. A block can be any concrete content payload: text, list, image, chart, table, code, metric, quote, timeline, or video.

For authoring convenience, OPF also accepts multiple root-level content payloads on a slide as shorthand for blocks, when placement is unspecified. This slide uses multiple root-level content payloads:

implicit-shorthand

{
  "title": "Evidence Snapshot",
  "text": "Jaguar populations are declining due to habitat fragmentation.",
  "chart": {
    "type": "line",
    "data": {
      "columns": [
        "Year",
        "Population Index"
      ],
      "rows": [
        [
          "2020",
          100
        ],
        [
          "2021",
          94
        ],
        [
          "2022",
          88
        ]
      ]
    }
  },
  "quote": {
    "text": "Jaguar conservation depends on connected habitat.",
    "attribution": "Field researcher"
  }
}

Renderers treat it as equivalent to explicit layout-agnostic blocks.

explicit-blocks

{
  "title": "Evidence Snapshot",
  "blocks": [
    {
      "text": "Jaguar populations are declining due to habitat fragmentation."
    },
    {
      "chart": {
        "type": "line",
        "data": {
          "columns": [
            "Year",
            "Population Index"
          ],
          "rows": [
            [
              "2020",
              100
            ],
            [
              "2021",
              94
            ],
            [
              "2022",
              88
            ]
          ]
        }
      }
    },
    {
      "quote": {
        "text": "Jaguar conservation depends on connected habitat.",
        "attribution": "Field researcher"
      }
    }
  ]
}

Block rules

This shorthand only applies at the slide root, and only when the slide has no explicit type, no blocks, and no promoted region keys such as left, right, or top:center.

Root-level payload fields include text, items, bullets, image, chart, table, code, metric, quote, timeline, and video.

Promoted regions

Promoted regions are slide-root keys such as left, right, center+right, and top:center. Each region contains one concrete content payload, and the key tells the renderer where that payload belongs, while the slide stays renderer-portable.

Region keys

OPF supports simple columns, simple rows, and row-column intersections.

Columns

left
center
right
left+center
center+right
left+center+right

Rows

top
middle
bottom
top+middle
middle+bottom
top+middle+bottom

Intersections

top:left
top:center
middle:right
bottom:center+right
top+middle:left+center

Region examples

A two-column slide can pin a table left and a chart across the remaining width.

regions-two-column

{
  "title": "Operating Snapshot",
  "left": {
    "table": {
      "columns": [
        "Metric",
        "Value"
      ],
      "rows": [
        [
          "Revenue",
          "$4.2M"
        ],
        [
          "Gross margin",
          "68%"
        ]
      ]
    }
  },
  "center+right": {
    "chart": {
      "type": "line",
      "data": {
        "columns": [
          "Month",
          "Revenue"
        ],
        "rows": [
          [
            "Jan",
            3.4
          ],
          [
            "Feb",
            3.8
          ],
          [
            "Mar",
            4.2
          ]
        ]
      }
    }
  }
}

A grid-style slide can combine row and column spans.

regions-grid

{
  "title": "Launch Readiness",
  "top:left": {
    "metric": {
      "value": "92%",
      "label": "Beta activation",
      "trend": "up"
    }
  },
  "top:center+right": {
    "text": "Customer teams are ready for phased rollout."
  },
  "middle+bottom:left+center+right": {
    "items": [
      "Finalize launch comms",
      "Confirm migration owners",
      "Prepare support coverage"
    ]
  }
}

Region rules

Region keys only apply at the slide root.
Region values are content payloads such as text, items, image, chart, table, metric, quote, or timeline.
Do not mix region keys with root payload fields such as text, chart, or blocks.
Do not use overlapping region keys on the same slide.

See the OPF schema reference for the full slide and content payload field list.