Settle a specification for "examples" structures

[wbamberg]

This PR contains a document that tries to describe the content structures for examples.

There's been talk of validating stumptown content, so I thought I'd try to start writing something we could use as a spec to validate content against. Also, there are some open issues around examples, and it would be good to have a place we can iron them out.

If this seems like a helpful doc I will try to write something similar for other things. I chose examples because they are relatively complicated.

@Elchi3 , @ddbeck , @peterbe , @chrisdavidmills , @escattone : it would be nice to get a few different perspectives on this.

[wbamberg]

Open issues/discussion points

Split sources

In Kuma, you can currently split up a single source into pieces, and disperse your descriptive text among the pieces, and the system will stitch them all together into a single live sample. Stumptown, as specified here, does not support this. I think it would get complicated to support both in code and in terms of specification, and I think it's enough of a niche case that it's OK to omit it. But maybe I'm wrong and it will turn out to be important.

Hidden sources

In Kuma, you can currently have sources which are included in the live sample but are not displayed. Stumptown, as specified here, does not support this at the moment, but I think we should. Especially this is to add some CSS to improve the appearance of examples. But I'm not sure what would be a good way to specify this (the obvious place would be the description.md front matter I guess).

An alternative might be just to have a good default CSS that we always include in live samples, which would also have the benefit of giving them a consistent appearance.

Optional titles

There's a slightly complicated rule about titles. They are optional, but if a page has any then all the examples in the page must have titles.

Here I've been guided by the current practice: we often have titles when there are multiple examples, and usually not when there is one. But in at least one case (<bdi>) we have multiple examples with no titles, because the examples are supposed to be connected.

I still think we should make titles optional, because otherwise it will be annoying for writers and we will probably get silly titles like "An example".

Should we omit width?

I included width because it's an argument to the EmbedLiveSample macro, which this grammar replaces. But actually the page layout tends to want to impose a width on the iframe anyway: there doesn't seem much point in specifying a narrower width than the page width, and specifying a wider width should have no effect (this is also true in Kuma). On the other hand perhaps width is useful for other possible consumers, and perhaps just our renderer should ignore it.

Should we have an explicit indicator for "I'm a live example"?

Currently the liveness of an example is indicated implicitly, by the presence or absence of width and height. Perhaps it would be better to have something explicit in the front matter. I think the reason I've not done this is that it introduces new error conditions: if an example says it's live but doesn't have width or height, that's an error.

Or maybe, non-live examples should not have separate source files, and just embed <pre> blocks in the descriptive text. Then the presence or absence of the example.* files is an indicator of liveness.

[ddbeck]

Why?

Wait, hold on. Let me make sure I understand the distinctions between examples here:

• descriptive: it's some markdown text?
• static: markdown with some fenced code blocks? Or is this markdown with some extra source files?
• live: these are the older style examples that are in an iframe and have the codepen and jsfiddle buttons?
• interactive: from mdn/interactive-examples?

It's not clear to me what distinction is being made between descriptive and static. It's also not clear to me what makes interactive examples a special case.

[wbamberg]

Why?

Wait, hold on. Let me make sure I understand the distinctions between examples here:

• descriptive: it's some markdown text?

• static: markdown with some fenced code blocks? Or is this markdown with some extra source files?

• live: these are the older style examples that are in an iframe and have the codepen and jsfiddle buttons?

• interactive: from mdn/interactive-examples?

Yes.

It's not clear to me what distinction is being made between descriptive and static.

Well yes this is a bit tenuous. The only point I was trying to make is that examples don't have to contain actual example code. But I could remove it as a separate category and just say that instead.

It's also not clear to me what makes interactive examples a special case.

Well... interactive examples are specified very differently[1], they live in a different bit of the MDN page, currently there should only be one in the page, and there are quite specific rules for the content they should contain, which is different from other examples.

It might be better to include them in here anyway, but it seemed more natural to list them separately.

[1] this might change: I don't very much like the way the interactive examples editor and sources are completely separate from MDN. We explored using CodePen as the editor for Web API examples, and in that case the examples would start to appear much more like "live samples" from the authoring point of view. But that work has stalled, and I don't know when if ever we will look at it again.

[ddbeck]

This is a bit convoluted. As an author, I'd prefer something like, "title is always required" with the understanding that not all consumers will use all titles all the time (e.g., render titles if and only if there is more than one example) or "title is always optional" with the understanding that a title will be generated if not provided (e.g., "Example 2").

As written, if there are three examples for an item and I want to write a fourth, then I have to look at three files to find out whether I need to specify a title or not (or wait on the linter to complain, I guess). That's not great.

[peterbe]

I agree with Daniel. It got complex. Perhaps, in the renderer we can simply be smarter about turning them into IDs because that's what sparked a lot of this discussion. Ie. tack on '-2' if a title is not distinct.

[wbamberg]

It's not really about IDs. It's about providing options to authors and deciding which options are worth the complexity.

"title is always required"

As I say, this would make people invent titles when they naturally wouldn't, in cases like <b> for example.

"title is always optional" with the understanding that a title will be generated if not provided (e.g., "Example 2").

This will prevent us from supporting cases like <bdi> where the author (me in this case :) wanted to use multiple live samples, but didn't want titles, because they should flow together.

These rules are the result of me looking through a bunch of pages to understand how people currently use the examples systems in MDN, and then making some choices about which usages we should continue to support in the future. I'm of course happy to change these choices but we ought to understand which usages we are excluding by doing so.

[ddbeck]

This will prevent us from supporting cases like where the author (me in this case :) wanted to use multiple live samples, but didn't want titles, because they should flow together.

Now that is interesting! It seems to me it'd be very nice to represent that as a single unit that happens to contain a few successive examples internally.

Maybe we could be slightly clever and embed the code in Markdown fenced code blocks and use the info string to alert our tooling to which is the example and what's just an ordinary code block:

(imagine that I'm not fighting the Markdown parser here):

You can use `<bdi>` to instruct the browser to treat the name in isolation from its embedding context:

``'html stumptown-renderme-flag
<ul>
 <li><bdi class="name">اَلأَعْشَى</bdi> - 1st place</li>
 <li><bdi class="name">Jerry Cruncher</bdi> - 2nd place</li>
</ul>
``'

[wbamberg]

I don't understand this, can you elaborate? In the <bdi> case, I do want to render all three sections as separate live samples. I just don't want headings.

Perhaps it might be better, as you imply, to allow authors to create a single "example" that can contain multiple "live samples" - that is to break the 1-1 relationship between abstract things called examples and concrete live sample code blocks+iframes. But that might be hard to express and to understand, for the sake of a rather niche usage.

[ddbeck]

I tried making a Markdown example of your original <bdi> example. Take a look here: https://gist.github.com/ddbeck/39d348b2561593955be4051fb8a1b72a

The idea here is that you'd capture the simple case—some explanatory text and some snippets of HTML, CSS, and JavaScript—in a single Markdown file. But it also works for the niche usage of successive, related examples.

For authors, this is pretty tidy. No requirement for an extra directory, since everything is contained in a Markdown file. Because we're using expected annotations on code fences, it plays nicely with GitHub and editor syntax highlighting. And if you want successive, closely-related examples (as in <bdi>) then you can have a single unit for authoring.

This is good for consumers too. In the case of <bdi>, the successive examples are really one single illustration of the tag taken together. If we had to break these up in Stumptown, then consumers would need to treat the full set of examples as a single unit. In my proposed formulation, any one example stands alone. This would let us do some interesting things with examples, too, like a code sample gallery, filterable by tag.

[wbamberg]

Thank you for the details!

Then it sounds as if in this proposal we're not (ever?) having separate source files for examples. Instead we have a single Markdown file (or presumably a single section in prose.md) that embeds fenced code blocks, with extra directives to tell stumptown/the renderer when the code blocks should be treated as live samples.

What's the operation of stumptown here? Is it something like:

• when you parse Examples, check every code block for a code block containing the "I'm a live sample" directive. If you find it, keep looking for code blocks containing the directive, until you find something else (like a <p>, say, or a code block that doesn't contain the directive.

• then all the code blocks you found constitute a single live sample. The result iframe containing those code blocks is to be embedded immediately after the last code block found

• if any of the code blocks don't also have the "show me" directive, don't include the code block in the rendered output.

Is that about right? I think if we were going to do this we should make things more explicit, and make the "I'm a live sample" directive embed an ID for the particular live sample, instead of relying on the order we encounter things.

html example-body example_1 show-codeblock
<ul>
 <li><span class="name">Henrietta Boffin</span> - 1st place</li>
 <li><span class="name">Jerry Cruncher</span> - 2nd place</li>
</ul>

and

html example-body example_2 show-codeblock
<ul>
 <li><span class="name">اَلأَعْشَى</span> - 1st place</li>
 <li><span class="name">Jerry Cruncher</span> - 2nd place</li>
</ul>

What is the JSON output like in this case? I guess it must be structured, to have separate items for the descriptions and the example sources, as it is now, and the build-json takes care of slicing the Markdown into the bits.

What about headings? Are they just supplied by the author now in the overall Markdown, and stumptown/the renderer don't represent any titles or add any headings? It's hard to see in this model how the renderer could insert headings, because it doesn't really know the heading context in the place it's adding the result iframe (I mean, the author could have H2 Examples/H3 Multiple audio tracks, then the example, or just have H2 Examples). Or is stumptown/the renderer supposed to keep track of the outline so it can create headings of the appropriate level? That seems quite complicated.

I'm not very happy about having authors supply headings for these things, as we get inconsistency: "JS" and "JavaScript", "Result" and "Output", different orders, headings sometimes present and sometimes not, and so on. This is the kind of mess that stumptown is supposed to help with.

For authors, this is pretty tidy.

Well... when I write live samples, I always write them as web pages first, because they have to work. It's only after I've got them working properly as web pages that I copy all the pieces into the Wiki.

So as an author I quite like the explicitness of separate source files for examples - when those examples are supposed to be executable instead of just illustrative.

But this is a thing we can and I hope will experiment with :).

This is good for consumers too... In my proposed formulation, any one example stands alone.

Then it sounds like you're saying that this bdi example is represented as a single example in the stumptown JSON. What would the data structures look like? I assume it wouldn't be a single blob of HTML, or would it?

In general I feel like this approach is much closer to the old Wiki way of "write a big blob of content with some directives embedded in it" so I'd probably need some convincing that it is a better approach, especially if it is only really intended to solve a relatively niche case that has other possible solutions.

[ddbeck]

First, I appreciate this is long and getting a big digressive. Should we take this to a separate issue along the lines of "Expressing examples in Markdown"? I don't want to hold up the whole PR over this tangent from whether or not examples must have a title.

Then it sounds as if in this proposal we're not (ever?) having separate source files for examples.

We could still have separate source files. Maybe some examples require fifty lines of (hidden) JS or something to work—in that case it might be cumbersome to have that code in a Markdown file. I was trying to capture the (hopefully simple and common) case of "here are ten lines of code that I want to show to the reader and also render in an iframe".

(or presumably a single section in prose.md)

No, I'm -1 on this. I still think it's a good idea to separate the examples from other prose. Examples are special: they will contain potentially executable code and will have lots of special considerations above and beyond ordinary prose because of that.

What's the operation of stumptown here? Is it something like:

[snip]

Yeah, pretty much how you described it. Though now that I've had it described back to me I'd probably tweak this or that to strengthen the defaults. For example, I'd probably show code blocks by default and use a flag to hide them and I'd probably rely on a type in the front matter to make all the code in the example live, unless a code block is explicitly suppressed (i.e., we could rely on the language identifier itself instead of an example-body flag). We're writing in the examples directory, so it should probably require special intention to get something other than a real live example.

Is that about right? I think if we were going to do this we should make things more explicit, and make the "I'm a live sample" directive embed an ID for the particular live sample, instead of relying on the order we encounter things.

Yep, that's a reasonable idea. As a matter of style, I'd want to disallow blocks of non-consecutive IDs (e.g., no putting parts of example 1 after example 2), but I'm OK with making the relationship between blocks explicit, when there's more than one.

What is the JSON output like in this case?

I thought it'd be mostly like what we're building now (I assume that we'd have slight variations for our different example types): some metadata about the example (e.g. title, size info if relevant, etc.) and a blob of HTML (containing the Markdown and example code converted to a single unit of HTML). I stuffed the iframe sources into data URIs to avoid dealing with multiple files in the final Markdown output, but I don't know if that's a terrible idea.

What about headings?

[And later] Then it sounds like you're saying that this bdi example is represented as a single example in the stumptown JSON. What would the data structures look like? I assume it wouldn't be a single blob of HTML, or would it?

Again, I think it's good to separate this stuff from the prose. For any example , I'd expect there would be a title in the front matter that becomes that example's title attribute (in the description object) and we wouldn't use a top-level heading in the Markdown content. In a case like <bdi>, we never even used a heading internal to the example (I think it wouldn't be outrageous to ban headings in examples outright). If we did want to allow headings in example Markdown, we could impose some sort of style that would be tractable for consumers to modify automatically (e.g., we'll only ever give you <h3>s).

So as an author I quite like the explicitness of separate source files for examples - when those examples are supposed to be executable instead of just illustrative.

That's fair. Admittedly, my proposal only really works if previewing stumptown content is pretty easy (eventually we'll want a tool that provides a more human-readable view of stumptown content as parsed by our tooling). It's definitely not easy yet, but that's a whole separate issue.

In general I feel like this approach is much closer to the old Wiki way of "write a big blob of content with some directives embedded in it"

I get this. And that's where getting the subtleties around default behavior right will make a big difference (e.g., writing code in an example file in an examples directory should lead to a rendered example, rather than having to explicitly flag code to be rendered). But I also think that things which are closely related ought to be close together—if structuring content requires us to grind it to bits then immediately glue them back together with a configuration file, then we need to rethink the content or the structure or both.

[wbamberg]

First, I appreciate this is long and getting a big digressive. Should we take this to a separate issue along the lines of "Expressing examples in Markdown"?

Well this PR is (perhaps unwisely :) called "Settle a specification" so this is in scope. However I think it's very hard to get to a conclusion remotely on issues like this.

What is the JSON output like in this case?

I thought it'd be mostly like what we're building now

Currently the JSON output is something like:

  "examples": [
      {
        "description": {
          "title": "Marking up an abbreviation semantically",
          "width": 672,
          "height": 192,
          "content": "<p>To mark up an abbreviation without providing an expansion or\ndescription, simply use <code>&lt;abbr&gt;</code> without any attributes, as seen in this example.</p>\n"
        },
        "sources": {
          "html": "<p>Using <abbr>HTML</abbr> is fun and easy!</p>\n"
        }
    }
]

As I understand it, in this proposal the source blocks live inline in the description, and are also duplicated as explicit sources so the renderer can initialize the iframe. And then I guess in the bdi case, there are three examples, with three separate prose blocks, that are split according to slightly subtle implicit rules:

  "examples": [
      {
        "description": {
          "title": "the first bdi example",
          "width": 672,
          "height": 192,
          "content": "some descriptive text about the first example
and embedded source blocks for the first example.
Truncated after the last source block that belongs to this example"
        },
        "sources": {
          "html": "duplicated source for the first example"
        }
    },
     {
        "description": {
          "title": "the second bdi example",
          "width": 672,
          "height": 192,
          "content": "some descriptive text about the second example
and embedded source blocks for the second example.
Truncated after the last source block that belongs to this example"
        },
        "sources": {
          "html": "duplicated source for the second example"
        }
    },
...
]

Is that basically right? So in the bdi case we are still modelling this as three examples?

It feels like part of the difference between this proposal and the original is about how explicit we want to be at communicating structure. In this proposal it's a lot more implicit: writers write something that looks like free flowing prose, and the tools reveal a structure in that.

Another part of the difference is how much control authors have over the way examples look in the rendered page. In the current proposal, the renderer could easily build live samples that look a lot like interactive examples, or like embedded CodePens, but in this proposal it feels more like each author controls how the text and code blocks will appear in the rendered page.

I think this has pros and cons: being too restrictive for authors could be annoying, but means we can make the pages more consistent (for example, in BCD authors have no control on how a compat table will look, and this is a good thing for everyone). I'm not sure yet where the balance ought to be here.

if structuring content requires us to grind it to bits then immediately glue them back together with a configuration file, then we need to rethink the content or the structure or both.

Well... we pretty much have to have it in bits in order to make live samples out of it. Currently in KumaScript we grind it into bits so we can do this. The main difference I can see here is that in the current proposal the writer supplies it in bits, and in this proposal the writer supplies it in a more unitary way and the JSON builder does more dismembering.

---

As I said before: I think it's really hard to get to a conclusion on questions like this when you have to do it all asynchronously and in writing. (again, it's very unfortunate you couldn't be with us last week).

This is especially true because we haven't tested the specification on a lot of pages or with real writers. Maybe there will be lots of cases where we need the extra flexibility of this approach, or writers will hate the shackles of the current one (and prefer less visible shackles :).

So unless I've missed something important here, I think I'd like to suggest we keep what we have for now and reconsider it (1) the next time we can discuss it face to face and (2) if any concrete experience suggests that the current proposal is not going to work very well.

[ddbeck]

OK, a few last words in this topic then. First the actual issue here, then the meta stuff:

And then I guess in the bdi case, there are three examples, with three separate prose blocks, that are split according to slightly subtle implicit rules

Ah, maybe this is we're getting a bit sidetracked. I did not mean for an example-in-Markdown to produce more than one example-in-JSON (the way prose.md produces multiple sections); I meant that an example-in-Markdown stood for one and only one example-in-JSON.

It was my sense that the bdi example was, semantically, one example that happens to contain three separate chunks of code internally. If you split the bdi example in three, the first two parts aren't independently meaningful (they don't even contain the <bdi> tag). I figured that if we could solve the problem of representing an indivisible sequence like bdi, then we'd also answer the question of whether titles should be required or optional (plus get ourselves some nice authoring bonuses).

And titles are what provoked this thread, after all. To speak directly to that issue: I still think we should require titles for all examples. If we're not solving this sequence-of-examples problem, then I'd prefer to push the challenge of deciding whether to show titles onto the renderer rather than putting the burden on authors. That said, this is not the hill I'm going to die on. If we're sticking with the original rule, then let the record show I didn't like it. 😄

---

Meta stuff: yes, sorry about the length of this discussion. I wish I had a good guideline for "this async discussion is going on too long, we should just have a call to sort it out quickly." Also, yes, I share your dissatisfaction with not getting to join you last week—in fact, I'm more agitated about it this week than I was last week (last week I was in the dark, but this week I'm in the dark with consequences).

[ddbeck]

I interpret this as "setting a width or height declares this example to be live". That seems kinda cryptic. Sufficiently cryptic to answer the question of "Should we have an explicit indicator for 'I'm a live example'?"

I'd much rather have a front matter field to make this type intent explicit: type: live or type: static or type: interactive and then the linter can provide more helpful error messages ("This static example should not have a width value").

[peterbe]

Actually, I can't imagine authoring an iframe with anything but "full fluid width". Like with textareas, they're almost always block displays and the width is as much as possible but the "rows" is a very interesting thing to be able to control.

In other words, switch to 'type: interactive' to determine if the renderer should use an iframe. And make the 'height' optional and say that the default height depends on the renderer's discretion.

[wbamberg]

Actually, I can't imagine authoring an iframe with anything but "full fluid width". Like with textareas, they're almost always block displays and the width is as much as possible but the "rows" is a very interesting thing to be able to control.

In other words, switch to 'type: interactive' to determine if the renderer should use an iframe. And make the 'height' optional and say that the default height depends on the renderer's discretion.

Agree on width but I'm not sure height should be optional. The renderer has no idea what would be a good height for a particular example, the author does. The height is optional in EmbedLiveSample, and as a result many examples don't fit properly. As an author I pretty much always give a height to EmbedLiveSample, because I care about how my example will look.

[ddbeck]

Suggested change

	description, simply use `<abbr>` without any attributes, as seen in this example.
	description, use `<abbr>` without any attributes, as seen in this example.

[ddbeck]

If we're going to write this up, that's fine, I understand why we're doing it. But I do like making the split between stumptown and consumers explicit. With that in mind, I'd characterize this as "rendering suggestions"

[peterbe]

You've already written it now but I think the documentation would be easier to maintain and easier to write if we stay away from saying too much about rendering. It would also send a nice signal that the content is just the content.

[ddbeck]

This is a great start, Will. Overall, I like where this is headed, but there are a few places where I figure fewer choices is probably better.

In Kuma, you can currently split up a single source into pieces, and disperse your descriptive text among the pieces, and the system will stitch them all together into a single live sample.

Can you give an example of this? I'm not sure I'm thinking of what you're thinking of.

Hidden sources

Maybe a hidden.css file with the example would do? But maybe this is the sort of thing where we should do without for a while and see if we really need it.

An alternative might be just to have a good default CSS that we always include in live samples, which would also have the benefit of giving them a consistent appearance.

Or that.

Optional titles

I commented on this issue inline too, but my short answer: either always optional or always required, but never sometimes.

Should we omit width?

Yes! Let's see how long we can go before we decide we must have it.

Should we have an explicit indicator for "I'm a live example"?

I vote yes. More on this inline, but having the author make their intent with regards to liveliness (or staticness or descriptiveness) explicit will make for more helpful linter errors.

[peterbe]

I'm willing to do the work on the renderer to make everything easier to the author. Less weird requirements on the titles. No need to specify an iframe width. And, can we just figure out if an iframe should be rendered based on looking at the presence of 'example.*' files.

[peterbe]

Suggested change

	To include examples for an item (e.g. the `<video>` element), set the `examples` key in the item's meta.yaml file. This key is specified as a list of paths. These might be relative to meta.yaml or absolute, in which case it must begin from the "/content" directory.
	To include examples for an item (e.g. the `<video>` element), set the `examples` key in the item's `meta.yaml` file. This key is specified as a list of paths. These might be relative to `meta.yaml` or absolute, in which case it must begin from the "/content" directory.

[wbamberg]

And, can we just figure out if an iframe should be rendered based on looking at the presence of 'example.*' files.

Not in this proposal, no, because you can have examples that are not live (have no output iframe) but that still want to present blocks of code, and they are expected to use separate example.* files for those blocks of code. In this doc these are called static examples.

The reason for that is the desire to treat code as code, whether it's executable in an iframe or not - so e.g. for linting it seems more convenient to separate the code from the descriptive text[1]. And also perhaps it's good to present static and live samples in a consistent way.

But perhaps these are not very strong reasons, and we should change this proposal to say: "if you want a live sample, use separate example.* files. If you just want a static example just use fenced code blocks in your description.md".

Writing this document is an attempt to get clarity on questions such as this :).

---

[1] Of course there will still exist code blocks embedded in Markdown, in other sections of the documentation (for example).

[peterbe]

It would be nice to be able to type ../shared-examples/some-example since it's something you'd just expect to work.

[peterbe]

I agree with Daniel. It got complex. Perhaps, in the renderer we can simply be smarter about turning them into IDs because that's what sparked a lot of this discussion. Ie. tack on '-2' if a title is not distinct.

[peterbe]

Actually, I can't imagine authoring an iframe with anything but "full fluid width". Like with textareas, they're almost always block displays and the width is as much as possible but the "rows" is a very interesting thing to be able to control.

In other words, switch to 'type: interactive' to determine if the renderer should use an iframe. And make the 'height' optional and say that the default height depends on the renderer's discretion.

[peterbe]

It could mention that they're all optional. Right?
But what if none of them are present?

[wbamberg]

It could mention that they're all optional. Right?

That's already mentioned just above: https://github.com/wbamberg/stumptown-experiment/blob/document-structures/docs/structures/examples.md#example-syntax

But what if none of them are present?

If it's a live example, that's an error. We could say that.

[peterbe]

Can we avoid the word "stumptown" here?

[peterbe]

You've already written it now but I think the documentation would be easier to maintain and easier to write if we stay away from saying too much about rendering. It would also send a nice signal that the content is just the content.

[wbamberg]

This is a great start, Will. Overall, I like where this is headed, but there are a few places where I figure fewer choices is probably better.

In Kuma, you can currently split up a single source into pieces, and disperse your descriptive text among the pieces, and the system will stitch them all together into a single live sample.

Can you give an example of this? I'm not sure I'm thinking of what you're thinking of.

No, sorry, I can't. I think it is rather rare. I expect some will come up eventually but at the moment I think we should exclude this case.

Hidden sources

Maybe a hidden.css file with the example would do?

I like this idea.

But maybe this is the sort of thing where we should do without for a while and see if we really need it.

I'm reasonably sure we will need something like this. Here's an example: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/progress_event#Examples - this would be a less useful example if we had to show all the CSS. I think it's much more questionable whether we need hidden HTML and JS. But yes, we can add it as needed.

Should we omit width?

Yes! Let's see how long we can go before we decide we must have it.

Should we have an explicit indicator for "I'm a live example"?

I vote yes. More on this inline, but having the author make their intent with regards to liveliness (or staticness or descriptiveness) explicit will make for more helpful linter errors.

OK, these both seem like popular choices :).

[wbamberg]

I've made some updates:

• just use description.md for static code samples. This means that separate example.* files are only for live samples.
• remove 'width'
• support 'hidden.css'
• minor editorial updates

Note that I didn't (yet) add an explicit indicator for live-sampleness. I think now that we only use example.* files for live samples, this seems like a clear enough indicator that it's going to be a live sample not to need one. But I'm not particularly dogmatic about that.