Learn

Use Learn to understand and apply the system. Use Standards when you need the governing contract.

Template Structure Issues

How to diagnose markdown-template structures that do not validate or do not render as expected.

Troubleshooting path

How to debug a broken template structure

Report problems are usually literal structure problems. The fastest fix is to inspect the markdown AST the way the validator sees it.

1Read the report shape literally

Start from the exact heading, table, list, or reference structure the schema expects.

2Compare the authored nodes

Match each block or inline node against the actual document shape.

3Check widths, order, and references

Confirm table widths, heading order, and reference definitions are correct.

4Fix the structure, not the symptom

Update the authored template document so it satisfies the intended markdown contract.

Small structural errors create large render surprises.

Public Cuddler Template v1.0.0 validates markdown-compliant template JSON, not a binding language. That means most report issues are structural: wrong heading order, malformed tables, unresolved reference-style links, or content that falls outside the allowed markdown shape.

When a template document does not validate or renders unexpectedly, the fastest path is to inspect the authored markdown AST literally and compare it to the governing Template Schema. Small differences in heading levels, table widths, list item shapes, or reference identifiers are enough to make a report invalid.

Checks That Catch Most Problems

  • Confirm the document starts with the required heading and section order.
  • Confirm every table align array matches the header cell count.
  • Confirm every table body row matches the header width.
  • Confirm every reference-style link or image resolves to a matching linkReferenceDefinition.

Common Mistakes

  • Omitting a required heading or using the wrong heading level.
  • Publishing a table with the wrong number of alignment entries.
  • Using a reference-style link or image without a matching definition.
  • Copying a section shape from a different document family without updating the schema.
  1. Compare the authored template JSON with the governing Template Schema side by side.
  2. Fix the smallest structural mismatch first, such as a heading, table, or reference definition.
  3. Validate again after the template structure is corrected.