diff --git a/files/en-us/mdn/contribute/markdown_in_mdn/index.html b/files/en-us/mdn/contribute/markdown_in_mdn/index.html index 818e94e7aa2cbbb..cbe432e813e1b3b 100644 --- a/files/en-us/mdn/contribute/markdown_in_mdn/index.html +++ b/files/en-us/mdn/contribute/markdown_in_mdn/index.html @@ -360,6 +360,187 @@

Heading IDs

Live samples

+

In MDN writers can create "live samples" in which code blocks (HTML, CSS, JavaScript) in the page are built into a document that's displayed in the page in an iframe. In this way authors can show code and its output together, and the displayed code is the code used to generate the output so there's no risk of the code and the output getting out of sync.

+ +

To create a live sample, writers use the \{{EmbedLiveSample}} KumaScript macro.

+ +

To find the code blocks that should belong to a live sample, we consider that page headings (H1-H6) implicitly divide up the document into nested sections. So, for example:

+ +
+  H1 Title
+  |
+  ├── Introductory prose content
+  │
+  ├── H2 Syntax
+  |   |
+  │   ├── Syntax code block
+  │   │
+  │   ├── H3 Parameters
+  |   |   |
+  │   │   └── Parameters prose content
+  │   │
+  │   └── H3 Return value
+  |       |
+  │       └── Return value prose content
+  │
+  └── H2 Examples
+      |   
+      └── H3 HTML
+      |   |
+      |   └── HTML code block
+      |
+      └── H3 JavaScript
+      |   |
+      |   └── JS code block
+      |
+      └── H3 Result 
+          |
+          └── \{{EmbedLiveSample}}
+
+ +

In this example there are eight sections, one for each heading. The sections defined by the H2 headings contain the sections defined by the H3 headings under them, and the top-level section defined by the H1 heading contains the entire document.

+ +

Given this model, the rule for finding the code blocks to include in a live sample is:

+ +
    +
  1. Define the immediate section as the most-nested section that directly contains the macro call itself.
    2. +
  2. Look for any code blocks in the immediate section. If you find any, they are the code blocks to use. Stop looking.
    3. +
  3. If you don't find any, go to the next level up, and look for any code blocks in that section. If you find any, they are the code blocks to use. Stop looking.
    4. +
  4. If you don't find any, repeat (3) until you find code blocks or until you reach the top-level of the document.
    5. +
  5. If you reached the top level and didn't find any code blocks, this is an error.
    6. +
  6. If you did find code blocks, build the document and insert the iframe where the macro call was found.
    7. +
+ +

For example, in the case above, the macro call is in H3 Result, so we would: +

    +
  1. look in H2 Examples > H3 Result, and not find any code blocks
    2. +
  2. go up to H2 Examples, and look there
    3. +
  3. find the code blocks in H2 Examples > H3 HTML and H2 Examples > H3 JavaScript, include them in the live sample, and stop looking.
    4. +
+

+ +
+  H1 Title
+  |
+  ├── Introductory prose content
+  │
+  ├── H2 Syntax
+  |   |
+  │   ├── Syntax code block
+  │   │
+  │   ├── H3 Parameters
+  |   |   |
+  │   │   └── Parameters prose content
+  │   │
+  │   └── H3 Return value
+  |       |
+  │       └── Return value prose content
+  │                                                  Second (final) search scope
+  └── H2 Examples                                             |
+      |                                                       |
+      └── H3 HTML                                             |
+      |   |                                                   |
+      |   └── HTML code block                                 |
+      |                                                       |
+      └── H3 JavaScript                                       |
+      |   |                                                   |
+      |   └── JS code block                                   |
+      |                                First search scope     |
+      └── H3 Result                          |                |
+          |                                  |                |
+          └── \{{EmbedLiveSample}}            |                |
+
+ +

Examples

+ +

The simplest example is where the code blocks and the macro call all live in the same immediate section. For example:

+ +
+<h2>Examples</h2>
+
+   <h3>Example1</h3>
+
+       JS-code-block-1
+       CSS-code-block-1
+       \{{EmbedLiveSample}}
+
+   <h3>Example2</h3>
+
+       JS-code-block-2
+       CSS-code-block-2
+       \{{EmbedLiveSample}}
+
+ +

In this page we have 2 live samples:

+ + + +

Another common pattern is where the macro call wants to use code blocks in a sibling section:

+ +
+<h2>Examples</h2>
+
+   <h3>Example1</h3>
+
+       <h4>JavaScript</h4>
+
+           JS-code-block-1
+
+       <h4>CSS</h4>
+
+           CSS-code-block-1
+
+       <h4>Result</h4>
+
+           \{{EmbedLiveSample}}
+
+   <h3>Example2</h3>
+
+       <h4>JavaScript</h4>
+
+           JS-code-block-2
+
+       <h4>CSS</h4>
+
+           CSS-code-block-2
+
+       <h4>Result</h4>
+
+           \{{EmbedLiveSample}}
+
+ +

This also produces 2 live samples:

+ + + +

This model also means that certain arrangements are not possible. For example:

+ +
+<h2>Examples</h2>
+
+   JS-code-block-1
+   CSS-code-block-1
+   \{{EmbedLiveSample}}
+
+   <h3>Example2</h3>
+
+       JS-code-block-2
+       CSS-code-block-2
+       \{{EmbedLiveSample}}
+
+ +

This will give unexpected results, because the \{{EmbedLiveSample}} call directly under H2#Examples will try to include the code blocks under H3#Example2.

+ +

Discussion reference

+ +

This issue was resolved in https://github.com/mdn/content/discussions/5803.

+

Inline styles

Superscript and subscript