Demo metadata

[bennypowers]

Check out an element demos page, for example alert. Notice anything? The demos are listed one by one, in order, and each demo has three-and-only-three features:

1. a title
2. a running demo iframe
3. read-only source code tabs

This is great for anyone already in-the-know, but it would be better to provide some optional html content for each demo, explaining what's going on and why this demo exists.

We could do this by adding content to the demo html files themselves, but that approach has drawbacks which are IMO prohibitive:

• adds noise to the demo html partials
• explanatory content would only be viewable inside the demo iframe
• some elements (jump links, navigation, etc) would not work well with explanatory content inside the demo iframe

An ideal solution, therefore, would be to declare demo metadata (i.e. html content, or a structure including html content) somewhere reasonable, and then pull that in to the page which renders each demo in the listing e.g. https://ux.redhat.com/elements/alert/demos/.

My heart tells me that the custom elements manifest is the correct place for this content, but at the moment, the schema for cem does not yet allow extensions (unlike the design tokens schema, which we use for exactly this purpose)

Assuming we can overcome the cem schema problem: I propose we add optional markdown files for each demo html file with the same name. i.e rh-alert.md for rh-alert.html and nested.md for nested.html. our tooling would then be written to append that content to each demo record in the CEM, and that would be used to generate the demo listing on https://ux.redhat.com

What say you all?

[markcaron]

@bennypowers I think the .md file is a great and very logical idea. And, I agree that reducing noise in the demo partials is important.

[zeroedin]

I'm good for the markdown file. Gives the separation we need right now without being over complex.