Representing AEM Content Fragments and Pages in Content Bus/Markdown

[trieloff]

In the attempt to get AEM customers to use their existing content with the standard Helix rendering pipeline and potential future custom compontent-based renderers, we need to find a good way to represent the deeply nested content structures of AEM in something that feels natural in the Markdown++ of the Content Bus.

I see following options:

1. YAML midmatter
2. More sophisticated tables
3. Markdown directives

YAML Midmatter

GitHub-flavored markdown has support for YAML frontmatter (a YAML document carrying metadata at the start of a markdown document). Helix extends this to support YAML at the start of a section, where sections can be anywhere in the document, but sections cannot be nested. An example document of Markdown with midmatter is here: https://github.com/adobe/helix-pipeline/blob/main/test/fixtures/frontmatter.md and the corresponding MDAST representation is here: https://github.com/adobe/helix-pipeline/blob/main/test/fixtures/frontmatter.json

Advantages:

• feels pretty natural
• straightforward mapping of JCR/JSON to YAML

Disadvantages:

• not used in Helix, because authoring tools (Word/GDocs) don't support it (this does not apply to AEM)
• YAML can only be added one level below the root of the document, once you are in YAML, there is no way to go back to Markdown

More Sophisticated Tables

What are components in AEM are Blocks in Helix. Blocks are authored in Word and Google Docs as Tables and represented in the content bus as HTML <table> tags. You can see these tables in action here: https://blog.adobe.com/en/publish/2021/12/13/introducing-creative-cloud-express.md Before rendering, they get converted into nested divs. We could expand on this approach and represent more complex AEM components as tables, and nested components as nested tables.

Advantages:

• we stay in HTML/Markdown (Markdown is a superset of HTML, so this is technically not a Markdown extension)
• already supported by Helix (although no nested component support - we treat a table within a table as an actual table)

Disadvantages:

• we need to define a mapping
• traversing the DOM gets slightly more complicated

Markdown Directives

Discussed here before #159 (comment) Markdown Directives are a proposed syntax extension to Markdown that allow arbitrary block and inline metadata. It is the favored approach to handling extensions in the unified ecosystem, but we dismissed them in the past because they look ugly and their benefit over the status quo (tables) wasn't clear, especially considering that Helix does not support nested blocks.

Advantages:

• we can use existing parser infrastructure
• we stay within the bounds of what some people see as reasonable Markdown

Disadvantages:

• not yet supported in Helix
• looks ugly

[trieloff]

Two more thoughts after discussing this briefly with @davidnuescheler:

1. the optimal representation of Helix blocks are Pandoc's grid tables, which look as close to the real thing as possible, and can carry information like alignment that authors like to use anyway. (we'd need to write or update a remark plugin - https://github.com/zestedesavoir/zmarkdown/tree/master/packages/remark-grid-tables could be a start)
2. how do we deal with the mismatch that AEM Components can contain other components, whereas Helix blocks are final? The same way how Helix deals with deeper nesting and re-use today: put the more deeply nested sub-components into a separate document and include this document as a fragment. This allows us to benefit from the simplicity of limited nesting, without cutting off the migration path.

[michaelmarth]

I cannot comment on your conclusion/proposal at this point, but the reasoning is backwards. The self-imposed restrictions of today's editing methods in Helix should not leak into the data model that is optimized for Sites.