@adobe/helix-md2jcr 1.2.20 → 1.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.3.0](https://github.com/adobe/helix-md2jcr/compare/v1.2.21...v1.3.0) (2026-06-08)
+
+
+### Features
+
+* **block-options:** support element grouping for block options ([#215](https://github.com/adobe/helix-md2jcr/issues/215)) ([7388c2d](https://github.com/adobe/helix-md2jcr/commit/7388c2dcf95252393c47fc8097235f4612916342)), closes [#214](https://github.com/adobe/helix-md2jcr/issues/214)
+
+## [1.2.21](https://github.com/adobe/helix-md2jcr/compare/v1.2.20...v1.2.21) (2026-06-08)
+
+
+### Bug Fixes
+
+* **container-blocks:** correctly detect omitted parent rows ([#212](https://github.com/adobe/helix-md2jcr/issues/212)) ([cf89ba4](https://github.com/adobe/helix-md2jcr/commit/cf89ba4f040b990db2bb40a9d1b374087d63668e))
+
 ## [1.2.20](https://github.com/adobe/helix-md2jcr/compare/v1.2.19...v1.2.20) (2026-06-03)
 
 

package/README.md

@@ -99,6 +99,19 @@ const xml = await md2jcr(markdown, options);
 console.log(xml);
 ```
 
+## Documentation
+
+- [Container Blocks](docs/container-blocks.md) — how container blocks map parent
+  properties and child items (the one-column / many-column rules, omitting parent
+  rows, and error cases). See also the
+  [container-block test fixtures](test/fixtures/blocks/core/container-block/README.md)
+  for a worked scenario-by-scenario breakdown.
+- [Block Options (Classes)](docs/block-options.md) — block option classes and
+  element grouping (`classes`, `classes_*`): how header options are routed to
+  fields by their options or boolean name-suffix.
+- [Field Hinting](docs/field-hinting.md) — using `<!-- field: name -->` to skip
+  ahead within a field group.
+
 ## Baseline XML Files
 Running the ./baseline-tests.sh script will detect any md file under test/fixtures and execute the convert2jcr node script.  
 The script will generate new xml files beside the md files it locates. This is helpful when making changes to the converter

package/baseline-tests.sh

@@ -90,8 +90,17 @@ if [ -n "$SPECIFIC_FILE" ]; then
   exit 0
 fi
 
-# Find all .md files recursively in the directory
-MD_FILES=$(find "$MD_DIR" -type f -name "*.md")
+# Find all .md files recursively in the directory.
+# Exclusions:
+#   - fixtures/bin: its .xml is a throwaway artifact generated and cleaned up by
+#     bin.test.js, so it has no committed baseline to diff against.
+#   - error-handling: these fixtures intentionally fail conversion, so running
+#     them through md2jcr is expected to error.
+#   - README.md: documentation, not a fixture.
+MD_FILES=$(find "$MD_DIR" -type f -name "*.md" \
+  -not -name "README.md" \
+  -not -path "*/fixtures/bin/*" \
+  -not -path "*/fixtures/blocks/error-handling/*")
 
 # Check if no .md files are found
 if [ -z "$MD_FILES" ]; then

package/docs/block-options.md

@@ -0,0 +1,115 @@
+# Block Options (Classes)
+
+Block options let an author pick variants of a block without creating a whole new
+block. They are expressed as CSS classes on the block and appear in the block
+header parentheses in markdown:
+
+```markdown
++--------------------------------------+
+| Teaser (variant-a, light, fullwidth) |
++======================================+
+| My title                             |
++--------------------------------------+
+```
+
+A model exposes block options through its `classes` fields. In the simplest case
+there is a single `classes` field that holds a free-form list of class names.
+
+## Element Grouping for Block Options
+
+When there are several options — especially mutually exclusive ones — it is
+easier for authors to use multiple fields. Following the
+[element grouping](https://www.aem.live/developer/component-model-definitions#element-grouping-for-block-options)
+naming convention, the **classes group** is the base `classes` field plus any
+`classes_<name>` field (the group name `classes` separated from the option name
+by an underscore):
+
+```jsonc
+{ "component": "select",      "name": "classes",            "options": [ "variant-a", "variant-b" ] }
+{ "component": "multiselect", "name": "classes_background", "options": [ "light", "dark" ] }
+{ "component": "boolean",     "name": "classes_fullwidth" }
+```
+
+When AEM renders the block, every field in the group collapses into one flat
+class list — `class="teaser variant-a light fullwidth"` — and that is what lands
+in the block header parentheses.
+
+## How md2jcr maps header options back to fields
+
+Going from markdown to JCR, md2jcr must route each option in the header back to
+the field it came from. Because the rendered class list is **flat** (it does not
+record which field produced each class), routing is driven by the field
+definition — **not by the order of the options**:
+
+- **Boolean field** — matched by its **name suffix** (the part after `classes_`).
+  The token `fullwidth` sets `classes_fullwidth="true"`. If the token is absent,
+  the field is left unset. This suits on/off toggles.
+- **Select / multiselect field** — matched by its **declared option values**. The
+  token `light` is routed to `classes_background` because `light` is one of that
+  field's options. A multiselect claims **all** of its matching tokens.
+- **Base `classes` field** — receives any leftover tokens that no more specific
+  field claimed. This also covers the common case of a single, free-form
+  `classes` field.
+
+Multi fields are written as `[a, b]`; single fields as a comma-separated value.
+
+### Example
+
+Given the model above and the header `Teaser (variant-a, light, fullwidth)`, the
+block node gets these properties:
+
+```text
+classes="variant-a"  classes_background="light"  classes_fullwidth="true"
+```
+
+A multiselect background claims every matching token:
+
+```text
+Teaser (variant-a, light, dark)
+  -> classes="variant-a"  classes_background="[light, dark]"
+```
+
+And an unmatched token falls back to the base `classes` field:
+
+```text
+Promo (highlight, featured, sticky)   // classes is free-form, classes_sticky is boolean
+  -> classes="[highlight, featured]"  classes_sticky="true"
+```
+
+The classes group fields are block options, not content, so they are excluded
+from `modelFields` and never consume content rows.
+
+## Requirements
+
+- Name grouped option fields `classes_<name>`.
+- A `classes_<name>` **select/multiselect must declare `options`** — that is how
+  its tokens are recognized.
+- A `classes_<name>` **boolean** needs no options; its name suffix is the class.
+- A **free-form text** `classes_<name>` field (no options) cannot be
+  reverse-mapped to its field — its token has no matching signal — so it falls
+  back to the base `classes` field. As the spec notes, block options are usually
+  select or multiselect, which avoids this.
+
+## Why options, not position?
+
+Mapping the first option to the first field, the second to the second, and so on
+seems simpler, but it breaks whenever the number of tokens does not equal the
+number of fields — which is common:
+
+- a boolean that is **off** contributes no token,
+- an empty select contributes no token,
+- a multiselect contributes **several** tokens.
+
+Any of these slides every following option into the wrong field. Matching by a
+field's declared options (and a boolean's name suffix) is order-independent and
+survives missing, optional, and multi-value fields.
+
+## Examples in the test suite
+
+Worked fixtures live under
+[`test/fixtures/blocks/core/block-options`](../test/fixtures/blocks/core/block-options):
+
+- `block-options-grouping` — single selects + a boolean that is on
+- `block-options-grouping-multi` — a multiselect claiming several values, boolean off
+- `block-options-grouping-fallback` — free-form base `classes` catch-all + a boolean
+- `block-options-grouping-booleans` — several independent boolean options, mixed on/off

package/docs/container-blocks.md

@@ -0,0 +1,154 @@
+# Container Blocks
+
+Container blocks are grid-table blocks that can create a parent block node and
+one or more child block item nodes. They are driven by three Universal Editor
+configuration files:
+
+- The parent component definition points to a parent model and a filter.
+- The filter lists the child component ids allowed inside the parent block.
+- Each child component definition points to the model used for that item row.
+
+## Table Shape
+
+The first row is always the block header. It names the parent block and can also
+include block classes:
+
+```markdown
++------------------------------------------------+
+| Vehicles (featured)                            |
++================================================+
+```
+
+Rows after the header can be parent property rows or child item rows.
+
+Parent property rows are single-cell rows. They map to the parent model fields
+in model order:
+
+```markdown
+| Planes, Trains, and Automobiles                |
+```
+
+Child item rows are normally multi-cell rows. The first cell can name the child
+component id, followed by optional classes separated with commas:
+
+```markdown
+| planewithclass, fast, wide | Field 1 | Field 2 | Field 3 |
+```
+
+When the child component id is present, md2jcr skips that first cell while
+mapping child model fields. In the example above, `fast` and `wide` are written
+to the child item's `classes` field when that field exists.
+
+## Omitting Parent Rows
+
+Container blocks can omit parent property rows entirely. When the first body row
+has more than one cell, md2jcr treats all body rows as child item rows:
+
+```markdown
++--------------------------------------------------------+
+| VehiclesWithClass (classy, vroom)                      |
++==========================+=========+=========+=========+
+| planewithclass, x, a     | Field 1 | Field 2 | Field 3 |
++--------------------------+---------+---------+---------+
+| trainwithclass, large    | Field 1 | Field 2 | Field 3 |
++--------------------------------------------------------+
+```
+
+The parent block still gets its default model, filter, name, and any classes
+from the header. No parent model properties are extracted from body rows.
+
+## Default Child Component
+
+If a child row does not start with an allowed child component id, md2jcr uses
+the first component listed in the parent filter. This allows simple child rows:
+
+```markdown
+| Field 1 | Field 2 | Field 3 |
+```
+
+That row maps to the first allowed child component as long as the cells match
+that child model's field groups.
+
+## One Column vs. Many Columns
+
+The simple rule that decides everything:
+
+- **one column = parent info** (a parent property row)
+- **two or more columns = a child item**
+
+```markdown
++----------------------------+
+| Cards                      |   <- the block name
++==============+=============+
+| My heading   |             |   <- ONE column  = parent info
++--------------+-------------+
+| card title 1 | card body 1 |   <- TWO columns = a child card
++--------------+-------------+
+| card title 2 | card body 2 |   <- TWO columns = a child card
++--------------+-------------+
+```
+
+A one-column row is always parent info. md2jcr does not try to guess whether you
+"meant" it to be a child — if you want a child item, give it more than one
+column.
+
+### A container can have parent info and no children
+
+This is allowed. A Cards block can carry block-level properties without any card
+items yet:
+
+```markdown
++----------------+
+| Cards          |
++================+
+| My heading     |   <- parent info, and zero cards. This is fine.
++----------------+
+```
+
+## Child Component Id Without Properties
+
+There is one one-column row that is **not** allowed: a single cell that contains
+only a child component id and nothing else.
+
+```markdown
++----------------+
+| Cards          |
++================+
+| card           |   <- one column, and the word is a child component id
++----------------+
+```
+
+A child item always needs more than one column (its component id followed by its
+property cells), so a lone component id is a half-finished child row — the author
+named the child but gave it no content. md2jcr stops with an error rather than
+quietly storing the component name as a parent property:
+
+```text
+Container block row in "Container": first body row has one cell ("card") which matches the child component "card" but has no property cells. Add the child item's properties as additional cells, or remove the component id if this is parent block data.
+```
+
+To fix it, add the child's property cells:
+
+```markdown
++----------------+-------------+
+| Cards          |             |
++================+=============+
+| card           | card body   |
++----------------+-------------+
+```
+
+Or, if the lone value really is parent info, change it so it no longer matches a
+child component name.
+
+## Best Practices
+
+- Use one column for parent info and two or more columns for child items.
+- Start child rows with the child component id whenever more than one child
+  component is allowed.
+- Never write a child component id on its own line without its property cells.
+
+## Examples
+
+For a worked, scenario-by-scenario breakdown of these rules — including omitted
+parent rows, empty parent properties, field hints, and the error case — see the
+[container-block test fixtures](../test/fixtures/blocks/core/container-block/README.md).

package/docs/field-hinting.md

@@ -4,17 +4,36 @@ This document provides guidance on modeling content in the Helix MD2JCR system,
 
 ## Field Hinting
 
-Field hinting is a powerful feature in the Helix MD2JCR system that allows you to explicitly specify which field in a component model should receive specific content from your markdown. This is particularly useful when the automatic field resolution doesn't match your intended content structure or when you need precise control over field mapping.
+Field hinting lets you skip ahead to a specific field **within a field group**
+when the automatic field resolution would otherwise assign content to an earlier
+field in that group. It is a tool for navigating *grouped* (collapsed) fields —
+the related fields a model collapses together, such as `teaserText_title`,
+`teaserText_subtitle`, and `teaserText_description`.
 
 ### Purpose of Field Hinting
 
-Field hinting serves several important purposes:
+The feature exists to skip over grouped fields you don't want to fill:
 
-1. **Precise Field Mapping**: When content doesn't naturally flow into the expected fields based on the model's field order, field hints allow you to explicitly direct content to specific fields.
+1. **Skip ahead within a field group**: When a group contains several related
+   fields and you only want to populate a later one, a hint jumps directly to it
+   and leaves the skipped fields unset.
 
-2. **Content Structure Control**: In complex components with multiple fields of the same type (e.g., multiple text fields), field hints ensure content goes to the correct field.
+2. **Precise mapping among similar grouped fields**: When a group has multiple
+   fields of the same type (e.g. several text fields), a hint ensures the content
+   lands on the intended one instead of the next one in sequence.
 
-3. **Sequential Field Mapping**: Field hints allow you to skip ahead to a specific field in the model's field sequence, but content must still be processed in the order it appears in the markdown.
+### Scope and Direction
+
+Two constraints follow from how this works, and they define what the feature is
+*not* for:
+
+- **Within a single field group only.** A hint splices the current group's
+  remaining fields. It cannot reach across separate, ungrouped top-level fields
+  (fields that do not share a group prefix) — those are resolved positionally,
+  not by hint.
+- **Forward only.** You can skip *ahead* to a later field in the group. A hint
+  that names a field already consumed is ignored, and the content flows into the
+  next available field. There is no way to hint backward.
 
 ### How Field Hinting Works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-md2jcr",
-  "version": "1.2.20",
+  "version": "1.3.0",
   "description": "Helix Service that converts markdown to JCR content structure",
   "main": "src/index.js",
   "type": "module",
@@ -74,12 +74,12 @@
     "husky": "^9.1.7",
     "junit-report-builder": "5.1.2",
     "lint-staged": "16.4.0",
-    "mocha": "11.7.5",
+    "mocha": "11.7.6",
     "mocha-multi-reporters": "1.5.1",
     "nock": "13.5.6",
     "semantic-release": "25.0.3",
     "unist-util-inspect": "8.1.0",
-    "yauzl": "3.3.0"
+    "yauzl": "3.3.1"
   },
   "lint-staged": {
     "*.js": "eslint"

package/src/mdast2jcr/domain/FieldGroup.js

@@ -9,6 +9,8 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
+import { isClassesField } from './Models.js';
+
 class FieldGroup {
   /**
    * Constructor.
@@ -35,7 +37,7 @@ class FieldGroup {
 
     this.model.fields
       .filter((field) => field.component !== 'tab')
-      .filter((field) => field.name !== 'classes')
+      .filter((field) => !isClassesField(field.name))
       .forEach((field) => {
         if (field.name.includes('_')) {
           const groupName = field.name.split('_')[0];

package/src/mdast2jcr/domain/Models.js

@@ -42,7 +42,19 @@ function getField(model, fieldName) {
 }
 
 /**
- * Return a list of field names in the model, excluding 'classes'.
+ * Returns true if the field name belongs to the `classes` block-options group —
+ * either the base `classes` field or a grouped `classes_*` option field
+ * (element grouping for block options).
+ * @param {string} name The field name.
+ * @return {boolean}
+ */
+function isClassesField(name) {
+  return name === 'classes' || name.startsWith('classes_');
+}
+
+/**
+ * Return a list of field names in the model, excluding the `classes` group
+ * (those fields are block options, not content).
  * @param {Model} model The model.
  * @return {Array<string>} An array of field names.
  */
@@ -51,7 +63,7 @@ function getModelFieldNames(model) {
     ? model.fields
       .filter((f) => f.component !== 'tab')
       .map((f) => f.name)
-      .filter((f) => f !== 'classes')
+      .filter((f) => !isClassesField(f))
     : [];
 }
 
@@ -59,4 +71,5 @@ export {
   getField,
   findModelById,
   getModelFieldNames,
+  isClassesField,
 };

package/src/mdast2jcr/hb/partials/grid-table.js

@@ -19,7 +19,7 @@ import { toHtml } from 'hast-util-to-html';
 import { getComponentById, getComponentByTitle, getModelId } from '../../domain/Definitions.js';
 import {
   findModelById,
-  getField, getModelFieldNames,
+  getModelFieldNames, isClassesField,
 } from '../../domain/Models.js';
 import { findAll } from '../../utils/mdast.js';
 import link from './supports/link.js';
@@ -38,6 +38,93 @@ import ModelHelper from '../../domain/ModelHelper.js';
  * @typedef {import('../../index.d.ts').Filter} Filters
  */
 
+// -- Block Options (classes) --------------------------------------------------
+
+/**
+ * Recursively collect every option `value` from a field's options tree
+ * (options may be nested under `children`).
+ * @param {Array<object>} options - The field's options array.
+ * @return {Array<string>} The flat list of option values.
+ */
+function collectOptionValues(options) {
+  return (options || []).flatMap((option) => {
+    if (option.children) {
+      return collectOptionValues(option.children);
+    }
+    return option.value !== undefined ? [option.value] : [];
+  });
+}
+
+/**
+ * Distribute block-option tokens (the classes from a block header, or the
+ * leading cell of a child item) across the model's `classes` group fields, per
+ * the AEM "element grouping for block options" rules:
+ *
+ * - a boolean field receives "true" when its name suffix (after `classes_`)
+ *   appears as a token (e.g. token "fullwidth" -> classes_fullwidth="true");
+ * - a text/select field with options claims the tokens that match its option
+ *   values (e.g. token "light" -> classes_background="light");
+ * - any remaining tokens fall back to the base `classes` field, which also
+ *   covers the common single-field case (a free-form `classes` field).
+ *
+ * Multi fields are written as `[a, b]`; single fields as a comma-separated list.
+ * @param {Model} model - The block or item model.
+ * @param {Array<string>} tokens - The option tokens.
+ * @return {Object<string, string>} A map of class field name to property value.
+ */
+function distributeBlockOptions(model, tokens) {
+  const groupFields = (model?.fields || []).filter((f) => isClassesField(f.name));
+  if (groupFields.length === 0 || tokens.length === 0) {
+    return {};
+  }
+
+  const remaining = [...tokens];
+  const assigned = new Map();
+
+  // boolean fields: the suffix after `classes_` becomes the option when present
+  groupFields
+    .filter((field) => field.component === 'boolean')
+    .forEach((field) => {
+      const suffix = field.name.replace(/^classes_/, '');
+      const idx = remaining.indexOf(suffix);
+      if (idx !== -1) {
+        assigned.set(field.name, true);
+        remaining.splice(idx, 1);
+      }
+    });
+
+  // text/select fields with options: claim the tokens that match their values
+  groupFields
+    .filter((field) => field.component !== 'boolean' && field.options)
+    .forEach((field) => {
+      const values = collectOptionValues(field.options);
+      const matched = remaining.filter((t) => values.includes(t));
+      if (matched.length > 0) {
+        assigned.set(field.name, matched);
+        matched.forEach((m) => remaining.splice(remaining.indexOf(m), 1));
+      }
+    });
+
+  // leftover tokens fall back to the base `classes` field (and the single-field case)
+  const base = groupFields.find((f) => f.name === 'classes' && f.component !== 'boolean');
+  if (remaining.length > 0 && base) {
+    assigned.set('classes', [...(assigned.get('classes') || []), ...remaining]);
+  }
+
+  const result = {};
+  assigned.forEach((value, name) => {
+    if (value === true) {
+      result[name] = 'true';
+    } else {
+      const field = groupFields.find((f) => f.name === name);
+      result[name] = field.multi === true ? `[${value.join(', ')}]` : value.join(', ');
+    }
+  });
+  return result;
+}
+
+// -- Block Header -------------------------------------------------------------
+
 /**
  * Locate the name of the Block and any classes that are associated with it.
  * Return null if the block name can not be found in the models.
@@ -80,6 +167,40 @@ function getBlockDetails(mdast, definition) {
   return null;
 }
 
+/**
+ * Extract the properties that are belong to the block header.  Properties like
+ * name, model id, and classes.
+ * @param {Array<Model>} models - the models object
+ * @param {Definition} definition - the definitions object
+ * @param {object} mdast - the mdast tree
+ * @return {{
+ *   name: string,
+ *   model: string,
+ *   classes?: string
+ * }}
+ */
+function extractBlockHeaderProperties(models, definition, mdast) {
+  const blockDetails = getBlockDetails(mdast, definition);
+  const props = {};
+
+  props.name = blockDetails.name;
+  if (blockDetails.modelId) {
+    props.model = blockDetails.modelId;
+  }
+
+  const model = findModelById(models, blockDetails.modelId);
+
+  // section metadata may not have a model. Distribute the header's block options
+  // across the model's classes group fields (element grouping for block options).
+  if (model) {
+    Object.assign(props, distributeBlockOptions(model, blockDetails.classes));
+  }
+
+  return props;
+}
+
+// -- Field Extraction Pipeline ------------------------------------------------
+
 /**
  * Process the field and collapse the field into the properties object.
  * @param id {string} - the id of the field
@@ -187,16 +308,6 @@ function extractPropertiesForNode(field, currentNode, properties) {
   }
 }
 
-function extractKeyValueProperties(row, model, fieldResolver, fieldGroup, properties) {
-  const [, ...nodes] = findAll(row, (node) => node.type === 'gtCell', true);
-
-  for (let i = 0; i < nodes.length; i += 1) {
-    const node = nodes[i];
-    const field = fieldResolver.resolve(node, fieldGroup);
-    extractPropertiesForNode(field, node, properties);
-  }
-}
-
 /**
  * Check if the node is a field name hint.
  * @param {Node} node - the node to check
@@ -288,6 +399,16 @@ function processCell(cell, fieldGroup, fieldResolver, properties) {
   }
 }
 
+function extractKeyValueProperties(row, model, fieldResolver, fieldGroup, properties) {
+  const [, ...nodes] = findAll(row, (node) => node.type === 'gtCell', true);
+
+  for (let i = 0; i < nodes.length; i += 1) {
+    const node = nodes[i];
+    const field = fieldResolver.resolve(node, fieldGroup);
+    extractPropertiesForNode(field, node, properties);
+  }
+}
+
 /**
  * Extract the properties for the block item.
  * @param {*} mdast - The mdast tree.
@@ -313,14 +434,10 @@ function extractProperties(
 
   // the first cells is the header row, so we skip it
   const rows = findAll(mdast, (node) => node.type === 'gtRow', false);
-  let classesField;
   if (mode === 'blockItem') {
-    classesField = getField(model, 'classes');
-    // if our model defines a classes field then dig out the classes from the first cell
-    if (classesField) {
-      // if we are a block item we need to look at the first cell to see if it has any class
-      // properties by inspecting the text value for any commas
-      // if there is a comma that then becomes the classes property for the block item
+    // if our model defines any classes group field then dig the block options out
+    // of the first cell (the component id followed by optional class names)
+    if ((model.fields || []).some((f) => isClassesField(f.name))) {
       const firstCell = rows[0].children[0];
       const textValue = toString(firstCell);
       const classes = textValue.split(',').map((c) => c.trim());
@@ -328,11 +445,8 @@ function extractProperties(
       // discard the component name leaving only the block option names (class names)
       classes.shift();
 
-      // if we are left with any classes to add to the block item, then add them
-      if (classes.length > 0) {
-        properties.classes = classesField?.multi === true
-          ? `[${classes.join(', ')}]` : classes.join(', ');
-      }
+      // distribute the options across the model's classes group fields
+      Object.assign(properties, distributeBlockOptions(model, classes));
     }
   } else {
     // get rid of the header row, no need for that
@@ -375,40 +489,29 @@ function extractProperties(
   }
 }
 
-/**
- * Extract the properties that are belong to the block header.  Properties like
- * name, model id, and classes.
- * @param {Array<Model>} models - the models object
- * @param {Definition} definition - the definitions object
- * @param {object} mdast - the mdast tree
- * @return {{
- *   name: string,
- *   model: string,
- *   classes?: string
- * }}
- */
-function extractBlockHeaderProperties(models, definition, mdast) {
-  const blockDetails = getBlockDetails(mdast, definition);
-  const props = {};
-
-  props.name = blockDetails.name;
-  if (blockDetails.modelId) {
-    props.model = blockDetails.modelId;
-  }
+// -- Container Block / Child Items --------------------------------------------
 
-  const model = findModelById(models, blockDetails.modelId);
-
-  // section metadata may not have a model
-  if (model) {
-    const classesField = getField(model, 'classes');
-
-    if (blockDetails.classes.length > 0 && classesField) {
-      props.classes = (classesField.multi === true)
-        ? `[${blockDetails.classes.join(', ')}]` : blockDetails.classes.join(', ');
-    }
-  }
+function getComponentId(cell) {
+  return stripNewlines(toString(cell)).split(',').shift().trim();
+}
 
-  return props;
+/**
+ * Builds the error thrown when a single-cell body row contains only a child
+ * component id with no property cells. A valid child item row is multi-column
+ * (the component id followed by its property cells), so a lone component id is a
+ * malformed child row and conversion cannot continue.
+ * @param {{name: string}} blockHeaderProperties - The parsed block header.
+ * @param {string} componentId - The child component id found in the cell.
+ * @return {Error}
+ */
+function childItemMissingPropertiesError(blockHeaderProperties, componentId) {
+  const message = [
+    `Container block row in "${blockHeaderProperties.name}": first body row has one cell ("${componentId}")`,
+    `which matches the child component "${componentId}" but has no property cells.`,
+    'Add the child item\'s properties as additional cells, or remove the component id'
+    + ' if this is parent block data.',
+  ].join(' ');
+  return new Error(message);
 }
 
 function getBlockItems(mdast, modelHelper, definitions, allowedComponents) {
@@ -455,6 +558,8 @@ function getBlockItems(mdast, modelHelper, definitions, allowedComponents) {
   return items;
 }
 
+// -- Entry Point --------------------------------------------------------------
+
 /**
  * The gridTablePartial function is a Handlebars partial that generates a block element.
  * @param {{models: Array<Model>,
@@ -531,12 +636,38 @@ function gridTablePartial(context) {
   // child component will, which will be handled in the Component Block Processing
   // section
   try {
+    const allowedComponents = modelHelper.getAllowedComponents(component);
+
+    // Pre-compute fieldGroup so it can be used for both detection and processing.
     if (model) {
       fieldGroup = modelHelper.getModelFieldGroup(model.id);
+    }
+
+    // Per the container-block spec, parent property rows are always single-column
+    // and child item rows are always multi-column. If the first body row has more
+    // than one cell, the author omitted parent rows entirely.
+    let hasParentRows = true;
+    if (fieldGroup && allowedComponents.length > 0) {
+      const allRows = findAll(mdast, (node) => node.type === 'gtRow', false);
+      const firstBodyRow = allRows[1]; // allRows[0] is the header gtRow
+      if (firstBodyRow) {
+        const firstCells = findAll(firstBodyRow, (n) => n.type === 'gtCell', false);
+        hasParentRows = firstCells.length === 1 && fieldGroup.fields.length > 0;
+        if (hasParentRows) {
+          const componentId = getComponentId(firstCells[0]);
+          if (allowedComponents.includes(componentId)) {
+            // a lone component id with no property cells is a malformed child row
+            throw childItemMissingPropertiesError(blockHeaderProperties, componentId);
+          }
+        }
+      }
+    }
+
+    if (model && hasParentRows) {
       extractProperties(mdast, model, mode, component, fieldGroup.fields, properties);
     } else {
-      // because we have no model we expect the block to have a filter with a component that does
-      // so that means we can remove the header row from the mdast tree
+      // no model, or model present but parent rows omitted - remove the header
+      // so getBlockItems only sees child item rows
       remove(mdast, (n) => is(n, { type: 'gtHeader' }));
     }
 
@@ -551,14 +682,13 @@ function gridTablePartial(context) {
     // 1. In this section attempt to locate the associated model for the block.
     // 2. Trim the mdast nodes to only be relevant for the child block.
     // 3. Then getBlockitems will process the mdast nodes and return the block items.
-    const allowedComponents = modelHelper.getAllowedComponents(component);
 
     // collect all rows
     const blockRows = findAll(mdast, (node) => node.type === 'gtRow', true);
     // the fieldGroup (parent model) determines the expected number of rows in the table
     // so we can remove the rows that belong to the parent and leave only the
     // relevant rows for the child
-    if (model) {
+    if (model && hasParentRows) {
       const removed = blockRows.splice(0, fieldGroup.fields.length + 1);
       // remove the elements from the mdast tree that match the items in the removed array
       removed.forEach((r) => {