mdn / mdn/rari

Consider replacing/revising EmbedLiveSample's API

Open
#339 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

idle
Dominant language
Rust
Stars
57
Forks
47
Avg merge
1d 11h
Merged PRs (30d)
68

Description

This comes out of https://github.com/mdn/yari/issues/4971.

To make it easier to write live samples, especially in Markdown and especially for translated content, we have a new way for the live sample macro to find the code blocks to use. In this new way the macro looks for code blocks in the same section of the document as the macro call itself. That makes the id argument to EmbedLiveSample redundant.

We've been experimenting with removing this argument an replacing it with an empty string, and fixing macros where this doesn't work (e.g. https://github.com/mdn/content/pull/10758).

At this point the EmbedLiveSample interface seems in need of some rework. It currently accepts 7 arguments:

  • $0 - The ID of the header block containing the sample: this would be made redundant
  • $1 - The width of the iframe (optional): this is already redundant
  • $2 - The height of the iframe (optional): this is still in use (although I would love it if Yari could calculate a sensible default for this from the content height).
  • $3 - The url of a screenshot of the sample working as intended (optional): this is occasionally used but we could perhaps look at deprecating it.
  • $4 - The slug from which to load the sample (optional; current page used if not provided): this is occasionally used but it would be great if we could deprecate it - Ryan told me it, (along with the {{page}} macro) is one of the most difficult bits of KS (because it introduces a build dependency)
  • $5 - The class name of the frame; defaults to "sample-code-frame": this used to be used to suppress the "Open in CodePen/JSFiddle" buttons, but now has no visible effect.
  • $6 - Allowed features, separated by semicolons (optional): this is used in a few places, to grant microphone, camera, and geolocation access to certain live samples. We could consider just giving all live samples the access needed here, but maybe it would be safer to keep this option.

So if we make the id redundant, of those 7 arguments:

  • 3 no longer do anything
  • we might want to deprecate or remove any or possibly even all of the remaining 4.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked yari issue 4971 and the EmbedLiveSample.ejs argument list at kumascript/macros/EmbedLiveSample.ejs#L5-L13. Review how the current live-sample macro is handled in Rari and identify which arguments remain necessary. Done means an agreed revised interface and corresponding updates to affected macro calls.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.