Some examples don't have titles

[peterbe]

▶ cat packaged/html/elements/address.json | jq .html.elements.address.examples
[
  {
    "description": {
      "width": 672,
      "height": 242,
      "content": "<p>This example demonstrates the use of <code>&lt;address&gt;</code> to demarcate the\ncontact information for an article&#39;s author.</p>\n<p>Although it renders text with the same default styling as the\n<a href=\"/en-US/docs/Web/HTML/Element/i\"><code>&lt;i&gt;</code></a>\nor <a href=\"/en-US/docs/Web/HTML/Element/em\"><code>&lt;em&gt;</code></a>\nelements, it is more appropriate to use <code>&lt;address&gt;</code> when dealing with\ncontact information, as it conveys additional semantic information.</p>\n"
    },
    "sources": {
      "html": "<address>\n  You can contact author at <a href=\"http://www.somedomain.com/contact\">\n  www.somedomain.com</a>.<br>\n  If you see any bugs, please <a href=\"mailto:[email protected]\">\n  contact webmaster</a>.<br>\n  You may also want to visit us:<br>\n  Mozilla Foundation<br>\n  331 E Evelyn Ave<br>\n  Mountain View, CA 94041<br>\n  USA\n</address>\n"
    }
  }
]

This is breaking mdn2 which could easily do something like {example.title || 'no title'} but since the title can be transformed and used for other things it might behoove us to make it required and add it to the list of validation things.

[wbamberg]

We currently use titles to make H3 headings for examples, which is usually desirable when there's more than one example.

Examples typically don't have titles when there is only one of them. For example, https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdo#Examples. In these cases (at the moment) there isn't an H3 heading, we have the example right under the H2: "Examples".

We could mandate titles in the content even in these cases, and if we did that we might also choose to include H3 headings in those cases, or we might choose to ignore the title if there's only one example, and put the example right under the H2 as they currently are (but I wonder what would be the point in mandating the title if we aren't going to use it).

My concern about mandating titles is that it will force people to invent pointless titles for examples:

## Examples

### My pointless title that stumptown forces me to write

// example source

Where there's more than one example, the author might well want to have titles to differentiate them.

## Examples

### My basic example

// example source

### My advanced example

// example source

Another slightly different case is something like this: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/bdi#Example: this has three live examples that are linked together. If titles are optional you can replicate this example in stumptown (although it is a little odd, as stumptown tends to consider examples are atomic, so you might want to rewrite the description a little). But if titles are mandatory then you can't.

I'm not sure whether examples must have titles although for the reasons above I tend to think they should be optional. In general though this is one of those areas where we have to try to understand how authors are currently using the tools they have and whether we should continue to support all those usages. At the moment authors have a ton of freedom in how they organize docs, so much so that the docs are not consistently organized. In stumptown they will have less freedom, but we should be sensitive to authors' current practice and try not to break important usages.

[peterbe]

If I understand you, it simply means that it's fine that some examples don't have titles and we need to cope gracefully with that.

If the examples do have titles, they need to be unique, right?

So the validation should be something like this:

const exampleTitles = examples.map(example => example.title);
if (exampleTitles.length > 1) {
  // If more than one title, they have to be unique.
  if ((new Set(exampleTitles)).size !== exampleTitles.length) {
    // At least one title is repeated
    throw new Error("When more than one example, the titles must be distinct");
  }
}

Beyond that, we already make the example.title optional with this line: https://github.com/peterbe/mdn2/blob/5f230925f7afe9a5217bc652142f187290e55d56/client/src/ingredients/examples.js#L65

[wbamberg]

This will throw an error if there are multiple examples with no title (as in the bdi example above). If we want to allow that case, then we should filter out undefined titles first. Also "// If more than one title, they have to be unique." is I think unnecessary since if there is only one title it is unique by definition.

So maybe something like:

const exampleTitles = examples.filter(e => !!e.title).map(e => e.title);
if ((new Set(exampleTitles)).size !== exampleTitles.length) {
  // At least one title is repeated
  throw new Error("When more than one example, the titles must be distinct");
}

?

Beyond that, we already make the example.title optional with this line

Yes. We also need to adjust the headings in https://github.com/peterbe/mdn2/blob/5f230925f7afe9a5217bc652142f187290e55d56/client/src/ingredients/examples.js#L10-L29 to be H3 if the title is omitted.

[peterbe]

Go for it.

[peterbe]

@wbamberg Can we close this now?

We stopped putting an ID on every iframe so we don't have to worry about repeated IDs. Also, we changed the rendering component to simply not bother displaying the title if the title doesn't exist.

Anything else?