Arguments for moving Interactive Examples into mdn/content + mdn/yari

[peterbe]

At the moment, we a completely separate infrastructure for producing URLs like https://interactive-examples.mdn.mozilla.net/pages/tabbed/video.html
The content is in https://github.com/mdn/interactive-examples and https://github.com/mdn/bob is used to compile the content into web pages.

I think it makes a lot of sense to merge all of this into mdn/content and mdn/yari. But it's possible to do only parts of that too. E.g. leave the content in github.com/mdn/interactive-examples but use mdn/yari instead of mdn/bob.

Pros

• mdn/content has "community" and stuff like write-access members and CODEOWNERS all figured out. In one place.
• monorepos's inherent advantages (e.g. all text content and examples all in one place which can make it easy and pleasant to make a PR that touches both)
• can remove all NPM publishing infrastructure in bob that is poorly maintained
• Fewer Devops things to maintain
• We can better control problems in the use of {{InteractiveExamples('something-twhats-a-typo')}} to avoid things like Issue with "RegExp.prototype.hasIndices": broken interactive example content#3784) rather than hoping it will work
• Both Yari and Interactive examples lack CSP and if it's all under one roof it'll be easier to make secure because fewer things to manage.

Cons

• impurity in that mdn/content ceases to be exclusively about one thing (the index.{html|md} files)
• monorepos' inherent disadvantages (e.g. if you file an issue you have to prefix that you're about to talk about an interactive example)
• interactive examples rarely change but if included in Yari they'd have to be rebuilt every 24h

[peterbe]

mdn/interactive-examples is still using TravisCI. In mdn/content we have all the GitHub Actions stuff figured out :)

[Ryuno-Ki]

Picking up on https://github.com/mdn/content/issues/4108 (and the issues linked from there) I have to admit, I got pretty confused.

I like our interactive demos, but I feel, there are different types of them inlined as iframe into the HTML.
Which kind of makes sense, since you can sandbox them this way instead of running the risk that they would dabble with the HTML around it.
Plus, you have a place to apply linters, tests etc.

So from a security and DX point of view, I'd vote for keeping the examples separate from the content.

The macro argument is similar to other data sources we use (like BCD). Perhaps a similar API could be queried?
(Like, GitHub API?)

[peterbe]

So from a security and DX point of view, I'd vote for keeping the examples separate from the content.

My discussion here is about whether it should be a separate repo or not.
Because interactive examples are potentially repeated on multiple pages (including the translations) it's smart that they're not tied to a specific page, like the live samples are. Sure. But the question is, are there strong enough benefits to lifting the interactive examples out of mdn/interactive-example and plopping them into mdn/content (separate from the regular index.html files)? ...and in the process, fold mdn/bob into mdn/yari instead.

[Ryuno-Ki]

If they would be included in mdn/content, would they still be deployed as a different origin in the final page?

[peterbe]

Yeah, the end result wouldn't change. It'd still be a dedicated different domain name.
But it'll be more similar to live samples.

[Ryuno-Ki]

Sounds like worth a PoC then.

[Ryuno-Ki]

First thing that spring into my mind:

Will give constructive feedback in the thread :)

[wbamberg]

I think this would be fine in principle. interactive-examples is a separate repo because when it was invented the content was in the Wiki. If the content had been in GitHub back then, interactive-examples would probably have gone in the same repo.

I think there are definitely advantages to contributors to be able to file one PR to add an interactive example and update the page at the same time. It's a bit hokey the way it is now.

At the moment you can do:

npm install
npm run start

and get a local server that serves the examples. This is nice! Would we get something similar?

How would we organize the files? Is the suggestion basically to have "interactive-examples" as a top level directory, alongside "files"?

What about other examples repos, notably https://github.com/mdn/css-examples and https://github.com/mdn/dom-examples (but there are others)? These are usually (but perhaps not always) designed to be run as github pages, and sometimes embedded in MDN pages using the EmbedGHLiveSample macro. Should we instead have:

/examples
  /interactive-examples
  /css-examples
  /dom-examples
  /...

?

Some day we should rationalize our examples system(s). I appreciate we don't want to do that as part of this proposal, but it would be good to try to make this a move that's at least compatible with a bigger plan.

@Rumyra might be interested in this discussion.

[peterbe]

By the way, not a single page, that isn't mdn/kitchensink or mdn/structures/code_examples uses more than 1 interactive example.

If we embed them within the content, and just use run-time Yari to preview, you don't need any additional tooling (e.g. npm run start). It would just be a matter of editing files/en-us/web/foo/bar/examples/interactive-examples/example1/index.js and reloading http://localhost:3000/en-us/docs/web/foo/bar

[wbamberg]

I think this would be fine, again in principle. I expect that tying the examples more closely to their pages would be a good thing overall. As you say, we've had these things a long time and haven't seen a lot of examples used in more than one page.

Lots of interactive example share things between themselves though, like common CSS or media assets, or fonts. So it would be nice to have a way to address that without it being a rats' nest.

By the way, not a single page, that isn't mdn/kitchensink or mdn/structures/code_examples uses more than 1 interactive example.

It at least used to be the case, in Kuma, that having >1 in a page broke stuff. But anyway yes, the current model for interactive examples is very specific: there's one per reference page, at the top of the page.

If we embed them within the content, and just use run-time Yari to preview, you don't need any additional tooling (e.g. npm run start). It would just be a matter of editing files/en-us/web/foo/bar/examples/interactive-examples/example1/index.js and reloading http://localhost:3000/en-us/docs/web/foo/bar

Yes please!

[peterbe]

Personally, I'd need to familiarize myself with more details to fully understand the implications of some interactive examples sharing assets like CSS. But I quite like the idea of co-locating stuff as much as possible.

[Rumyra]

I am on board with moving interactive examples into content or yari. My pref would be content with co-location. It would certainly make the workflow of adding/updating interactive examples easier.

Apologies if I've missed some discussion about this, but would they still be embedded in an iframe, or run within the page?

[peterbe]

would they still be embedded in an iframe, or run within the page?

Yes.
There might a future where we stop needing an iframe because we've security-vetted all interactive examples.

But still, a way to break this up is to just rearrange how content (no pun intended) is organized. We'd probably need to rewrite bob which is the code that packages the interactive example into an HTML page that would be served inside the iframe.
If we do that, apart from minor differences in the bob -> Yari builder the end-user wouldn't notice any differences.

Heck, it might be easiest to first just put the bob code into mdn/yari so as to not break what's working.