Content Model
The content model is structural first. In the active runtime, reusable components are authored through shortcode grammar, rendered through component-specific renderers, and styled by plugin or shell CSS depending on ownership. The model is therefore not a generic rich-text system. It is a set of explicit structures, each with its own allowed fields, optional content, and fallback behaviour.
The most important distinction is between structure, prose, media source, and presentation. Structure is the shortcode grammar itself: az_visual, az_item, az_field, az_list, az_section, az_example, az_case_section, az_case_figure, az_case_video, and the other authored tags. Prose is the text carried inside those structures. Media source is the file or URL that a structure points to, such as a case-study figure src, a case-study video url, or the uploaded SVG assets used by the Geometries of Use specimen. Presentation is the renderer markup plus the CSS that turns the parsed data into a page.
Because of that separation, content should be written for the grammar that owns it. Structure belongs in shortcode tags and attributes. Prose belongs inside authored blocks. Media belongs in the specific media fields that the parser expects. Layout belongs to the renderer and CSS, not to inline authoring.
- Shortcode tags define structure; they are the only confirmed structural language in the plugin runtime
- Prose belongs inside authored fields, bodies, sections, and examples
- Lists are authored as plain lines inside az_list blocks and normalized by the parser
- Media belongs in dedicated source fields such as src or url, not inside prose
- Renderers decide layout, hierarchy, and omission of empty regions
- Page templates and shell patterns assemble organisms into whole-page experiences
Shared structural patterns
Across the live runtime, the most common shared pattern is item-plus-fields. The generic visual parser reads az_item blocks, collects az_field name values, normalizes az_list content into point arrays, and turns az_section or az_substep content into titled body sections. That pattern powers the validated tabbed / indexed reader family.
The docs path uses a narrower grammar. az_docs accepts az_field name=”intro” and az_field name=”body”, a top-level az_list name=”points”, nested az_section blocks, and nested az_example blocks. The docs renderer then decides whether the current page is acting as an overview or as a section detail view.
The case-study family is separate and explicit. It uses az_case_hero, az_case_facts, az_case_fact, az_case_section, az_case_figure, az_case_video, az_case_related, and az_case_link rather than the generic az_item grammar.
Confirmed prose rules
Prose policy is not identical across every family, so only confirmed behaviour should be treated as system guidance.
In the live case-study runtime, prose is plain text only. The parser removes HTML authoring, strips accidental Markdown-style heading markers at the start of lines, and keeps paragraph breaks readable. That policy currently applies to hero body, section body, related-link summaries, and lead intro for case studies.
In the active docs path, intro, body, section prose, and example prose are flattened to text by the docs parser before rendering. That means docs content should also be treated as structured plain text rather than as a hidden HTML authoring channel.
Other validated visual families store authored text and render it as prose, but this pass does not define a stricter global prose policy beyond the cases explicitly confirmed above.
Field, list, and section behaviour
az_field blocks store named text values. In the generic item parser, the field name is normalized to lowercase, so authored names such as principleDesc are read as principledesc in the parsed data. That is why renderer mappings must use the normalized key, not the original mixed-case spelling.
az_list blocks are parsed as line-based lists. Leading hyphens are stripped, empty lines are ignored, and the renderer receives a clean array of points.
az_section blocks store a title plus body text. In the tabbed reader family, they become narrative sections inside the main reading column. In the docs family, they become titled documentation blocks that can also contain examples and points. In the case-study family, section content is carried through the dedicated az_case_section tag because that family also needs ordered media and related-link handling.
Media handling rules
Confirmed media handling is currently strongest in the case-study family. az_case_figure requires a src value and may also carry alt, label, and caption. az_case_video requires a url value and may also carry title, label, and caption. These media nodes are preserved in authored order alongside narrative sections rather than collapsed into generic prose fields.
The case-study renderer groups consecutive media entries into a media grid while keeping their place in the overall flow. Video embeds attempt normal oEmbed rendering first and fall back to a visible link if embed resolution fails.
The Geometries of Use facilitation specimen uses a different media path. Its SVG artefacts are not shortcode-authored; they are loaded from the uploads directory by the theme pattern and laid out through shell CSS as page-owned specimen parts.
Required, optional, and fallback behaviour
Evidence in the active runtime shows that requirements vary by family.
- Tabbed / indexed reader: useful output depends on authored az_item blocks; if no items are parsed, the renderer returns empty output
- Ecosystem visual: requires an authored scenario field and at least one az_node; missing either condition returns a WP_Error from the parser
- Law visual: requires at least one az_law_reg block; missing regulations returns a WP_Error from the parser
- Case study: hero, facts, related links, and lead are optional; empty optional regions are omitted cleanly by the renderer
- Case study media: figure src and video url are required for those nodes to survive parsing
- Docs: detail content is optional; a docs page can still render title and navigation even when the detail payload is sparse
Examples
Tabbed reader authoring pattern
The validated tabbed family uses az_visual plus az_item children. Each item can carry named az_field values, line-based az_list blocks, and az_section blocks. The renderer then decides what belongs in the main reading column and what belongs in the support rail.
- Wrapper: az_visual id="AZ-ORG-TAB-01″ or another live tabbed id
- Children: az_item blocks with id, num, short, title, and optional url
- Shared content blocks: az_field, az_list, az_section, az_substep
- Support-rail fields are renderer-mapped, not free-floating layout instructions
Case-study authoring pattern
The validated case-study family uses a dedicated grammar because the page needs ordered story sections, media nodes, and related links without losing authored order.
- Wrapper: az_visual id="AZ-PAG-PRT-02″
- Required structure for useful output: authored az_case_section blocks, usually alongside az_case_hero and az_case_facts
- Media nodes: az_case_figure src="" and az_case_video url=""
- Related links: az_case_related with az_case_link children
- Prose is treated as plain text only in this family
Docs section authoring pattern
The active docs path is its own content model. The page content itself is the source for the docs section that az_docs renders.
- Wrapper: az_docs section="content-model" or another docs section slug
- Allowed top-level fields: intro, body, and points
- Allowed nested structures: az_section and az_example
- Docs prose is flattened to text by the parser before rendering