From 61a1e333fb224337d77dc694a686cba8daae49ee Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 17 Jul 2023 17:24:31 +0200 Subject: [PATCH 1/6] chore: add some documentation about embedlivesample identifiers --- .../page_structures/code_examples/index.md | 111 --------- .../page_structures/live_samples/index.md | 223 +++++++++++++++--- 2 files changed, 196 insertions(+), 138 deletions(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md index f542ff3357df81e..afba77d0c4f1f7e 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md @@ -77,117 +77,6 @@ The [`EmbedInteractiveExample`](https://github.com/mdn/yari/blob/main/kumascript Traditional live samples are inserted into the page using the [`EmbedLiveSample`](https://github.com/mdn/yari/blob/main/kumascript/macros/EmbedLiveSample.ejs) macro. An \\{{EmbedLiveSample}} call dynamically grabs the code blocks in the same document section as itself and puts them into a document, which it then inserts into the page inside an {{htmlelement("iframe")}}. See our [Live samples guide](/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples) for more information. -### Formatting live samples - -If you write a live sample in the "Examples" section, provide a descriptive H3 heading (`###`) for this live sample example. Ideally, write a short description of the example explaining the scenario and what you are hoping to demonstrate. Then add subsections with following H4 headings (`####`), in the order listed: - -- HTML -- CSS -- JavaScript -- Result - -Write the code blocks in the respective subsections listed above. - -In the **Result** subsection, add the call to the [`EmbedLiveSample` macro](/en-US/docs/MDN/Writing_guidelines/Page_structures/Live_samples#live_sample_macros). Preferably, include some more prose in this subsection to describe the result. - -If you're not using a particular language type (for example, if you are not using JavaScript) or if you are hiding it, then you should omit the corresponding heading. - -For example: - -````md -## Examples - -### Styling a paragraph - -In this example, we're using CSS to style paragraphs that have the `fancy` class set. - -#### HTML - -```html -

I'm not fancy.

- -

But I am!

-``` - -#### CSS - -```css -p.fancy { - color: red; -} -``` - -#### Result - -\{{EmbedLiveSample("Styling a paragraph")}} - -Only the `

` element with `class="fancy"` will get styled `red`. -```` - -### Hidden code - -Sometimes you just want to display the static code block that is pertinent to the example rendered within a page. However you still need HTML, CSS and JavaScript to render such an example. - -To achieve this you can hide any code blocks that are not relevant with the `hidden` class. If you do this, omit the `### HTML/CSS/JavaScript` headings for the hidden code blocks. - -Using the example above but hiding the HTML code would look like this: - -````md -## Examples - -### Styling a paragraph - -In this example, we're using CSS to style paragraphs that have the `fancy` class set. - -```html hidden -

I'm not fancy.

- -

But I am!

-``` - -#### CSS - -```css -p.fancy { - color: red; -} -``` - -#### Result - -\{{EmbedLiveSample("Styling a paragraph")}} - -Only the `

` element with `class="fancy"` will get styled `red`. -```` - -### Live example demo - -### Styling a paragraph - -In this example, we're using CSS to style paragraphs that have the `fancy` class set. - -#### HTML - -```html -

I'm not fancy.

- -

But I am!

-``` - -#### CSS - -```css -p.fancy { - color: red; -} -``` - -#### Result - -\{{EmbedLiveSample("Styling a paragraph")}} - -Only the `

` element with `class="fancy"` will get styled `red`. - ## GitHub live samples GitHub live samples are inserted into the page using the [`EmbedGHLiveSample`](https://github.com/mdn/yari/blob/main/kumascript/macros/EmbedGHLiveSample.ejs) macro. An \\{{EmbedGHLiveSample}} call dynamically grabs the document at a specified URL (which has to be inside the **mdn** GitHub organization), and inserts into the page inside an {{htmlelement("iframe")}}. diff --git a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md index 19011fde0f8751a..8513cb0923c89a1 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md @@ -6,31 +6,109 @@ page-type: mdn-writing-guide {{MDNSidebar}} -MDN supports turning sample code displayed in articles into running samples the reader can look at in action. These are called _live samples_ and allows users to see what code output looks like. It also makes documentation more dynamic and instructive. +MDN supports turning code blocks in articles into running samples the reader can see in action. These are called _live samples_ and allows users to see what code output looks like. It also makes documentation dynamic and instructive. -These live samples can include HTML, CSS, and JavaScript in any combination. Note that "live" samples are _not interactive_; however, they do ensure that the output displayed for a sample matches the code of the sample exactly, because it is actually generated by the code sample. +These live samples can include HTML, CSS, and JavaScript in any combination. Note that "live" samples are _not interactive_; however, they do ensure that the output for a sample matches the source of the sample exactly, because the generated samples run the code in the page directly. ## How does the live sample system work? -The live sample system gathers up all the code in a group, merges it into one HTML file, and then renders that HTML in an {{HTMLElement("iframe")}}. A live sample therefore consists of two pieces: +The live sample system groups code blocks, merges them into HTML and renders the HTML in an {{HTMLElement("iframe")}}. +A live sample consists of two parts: -- A group of code blocks -- The macro call that (creates the frame or the link that) displays the result of the code blocks +- One or more code blocks grouped together +- A macro call that shows the result of the combined code blocks in an {{HTMLElement("iframe")}} -A "group" of code blocks, in this context, is identified by the ID of a heading or a block element (such as a {{HTMLElement("div")}}). +Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#example_code_blocks) containing code for the sample has a language identifier on it that indicates whether it's HTML, CSS, or JavaScript code; these are `html`, `css`, and `js`. The language classes must be on the corresponding blocks of code and a macro call must be present in the page to display the sample: + +````md +## Examples + +```html + +``` + +```css +/* CSS code */ +``` + +\{{EmbedLiveSample("Examples")}} +```` + +### Grouping code blocks + +Code blocks can be grouped in two ways: + +1. Using the ID of a heading or a block element that contains the code blocks +2. Using a string identifier in code blocks + +Code blocks that do not use an explicit identifier are grouped together using the ID of the heading or block element that contains the code blocks. +The identifier in this case is the ID of a heading or a block element (such as a {{HTMLElement("div")}}), for example: + +````md +## Examples + +### Styling a paragraph + +In this example, we're using CSS to style paragraphs that have the `fancy` class set. + +#### HTML + +```html +

I'm not fancy.

+ +

But I am!

+``` + +#### CSS + +```css +p.fancy { + color: red; +} +``` + +#### Result + +\{{EmbedLiveSample("Styling a paragraph")}} + +Only the `

` element with `class="fancy"` will get styled `red`. +```` - If the ID belongs to a block element, the group includes all the code blocks within the enclosing block element whose ID is used. -- If the ID belongs to a heading, the group includes all the code blocks that are after that heading and before the next heading of the same heading level. Note that code blocks under subheadings of the specified heading are all used; if this is not the effect you want, use an ID on a block element instead. +- If the ID belongs to a heading, the group includes all the code blocks that are after that heading and before the next heading of the same heading level. Note that code blocks under subheadings of the specified heading are all used; if this is not the effect you want, use an ID on a block element or use a string identifier instead. -The macro uses a special URL to fetch the sample code for a given group, for example `https://yari-demos.prod.mdn.mozit.cloud/en-US/docs/Web/CSS/animation/_sample_.Cylon_Eye.html`. The general structure is `https://url-of-page/_sample_.group-id.html`, where `group-id` is the ID of the heading or block where the code is located. +To group code blocks using a string identifier, add the identifier to the code blocks as a class after the language identifier in the form `live-sample___{IDENTIFIER}`, for example, `live-sample___color-picker`. +The following example groups a CSS and a JavaScript code block together using the identifier `color-picker`: -The resulting frame (or page) is sandboxed, secure, and technically may do anything that works on the Web. Of course, as a practical matter, the code must contribute to the point of the page that contains it; random stuff running on MDN will be removed by the editor community. +````md +## Examples + +### Styling a paragraph + +In this example, we're using CSS to style paragraphs that have the `fancy` class set. + +```html live-sample___paragraph-styling +

I'm not fancy.

+ +

But I am!

+``` + +```css live-sample___paragraph-styling +p.fancy { + color: red; +} +``` + +Only the `

` element with `class="fancy"` will get styled `red`: -> **Note:** You **must** use the macro for presenting the live sample's output. +\{{EmbedLiveSample("paragraph-styling")}} +```` -Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#example_code_blocks) containing code for the sample has a language identifier on it that indicates whether it's HTML, CSS, or JavaScript code; these are "html", "css", and "js". These classes must be on the corresponding blocks of code. +The macro uses a special URL to fetch the sample code for a given group, for example `https://yari-demos.prod.mdn.mozit.cloud/en-US/docs/Web/CSS/animation/_sample_.Cylon_Eye.html`. The general structure is `https://url-of-page/_sample_.group-id.html`, where `group-id` is the ID of the heading or block where the code is located. + +The resulting frame (or page) is sandboxed, secure, and technically may do anything that works on the Web. Of course, as a practical matter, the code must contribute to the point of the page that contains it; random stuff running on MDN will be removed by the editor community. -The live sample system has lots of options available, and we'll try to break things down to look at them a bit at a time. +The live sample system has lots of options available, and we'll try to break things down to look at them one bit at a time. ### Live sample macros @@ -44,11 +122,12 @@ In many cases, you may be able to add the `EmbedLiveSample` or `LiveSampleLink` #### EmbedLiveSample macro ```plain -\{{EmbedLiveSample(block_ID, width, height, screenshot_URL, page_slug)}} +\{{EmbedLiveSample(sample_id, width, height, screenshot_URL, page_slug)}} ``` -- block_ID - - : Required: The ID of the heading or enclosing block to draw the code from. The best way to be sure you have the ID right is to look at the URL of the section in the page's table of contents; you can also check it by viewing the source of the page. +- sample_id + - : Required: This can be the string identifier of the sample or the ID of the heading or enclosing block to draw the code from. + To verify if you have the correct heading ID is to look at the URL of the section in the page's table of contents; you can also check it by viewing the source of the page. - width - : The width of the {{HTMLElement("iframe")}} to create, specified in `px`. This is optional; a reasonable default width will be used if you omit this. Note that if you want to use a specific width, you _must_ also specify the height parameter. - height @@ -76,12 +155,60 @@ In many cases, you may be able to add the `EmbedLiveSample` or `LiveSampleLink` The sections below describe a few common use cases for the live sample system. -### Turning snippets into live samples +### Formatting live samples -One common use case is to take existing code snippets already shown on MDN and turn them into live samples. +If you write a live sample in the "Examples" section, provide a descriptive H3 heading (`###`) for this live sample example. Ideally, write a short description of the example explaining the scenario and what you are hoping to demonstrate. Then add subsections with following H4 headings (`####`), in the order listed: + +- HTML +- CSS +- JavaScript +- Result + +Write the code blocks in the respective subsections listed above. + +In the **Result** subsection, add the call to the `EmbedLiveSample` macro. Preferably, include some more prose in this subsection to describe the result. + +If you're not using a particular language type (for example, if you are not using JavaScript) or if you are hiding it, then you should omit the corresponding heading. + +### Hidden code + +Sometimes you just want to display the static code block that is pertinent to the example rendered within a page. However you still need HTML, CSS and JavaScript to render such an example. + +To achieve this you can hide any code blocks that are not relevant with the `hidden` class. If you do this, omit the `### HTML/CSS/JavaScript` headings for the hidden code blocks. -#### Prepare the code samples +Using the example above but hiding the HTML code would look like this: +````md +## Examples + +### Styling a paragraph + +In this example, we're using CSS to style paragraphs that have the `fancy` class set. + +```html hidden +

I'm not fancy.

+ +

But I am!

+``` + +#### CSS + +```css +p.fancy { + color: red; +} +``` + +#### Result + +Only the `

` element with `class="fancy"` will get styled `red`. + +\{{EmbedLiveSample("Styling a paragraph")}} +```` + +### Turning snippets into live samples + +One common use case is to take existing code snippets already shown on MDN and turn them into live samples. The first step is to either add code snippets or ensure that existing ones are ready to be used as live samples, in terms of the content and in terms of their markup. The code snippets, taken together, must comprise a complete, runnable example. For example, if the existing snippet shows only CSS, you might need to add a snippet of HTML for the CSS to operate on. Each piece of code must be in a code block, with a separate block for each language, properly marked as to which language it is. Most of the time, this has already been done, but it's always worth double-checking to be sure each piece of code is configured with the correct syntax. This is done with a language identifier on the code block of `language-type`, where _language-type_ is the type of language the block contains, e.g. `html`, `css`, or `js`. @@ -96,9 +223,9 @@ This section is the result of using the live sample template button to create no You may choose to delete any of these you wish; if you don't need any script, just delete that heading and its code block. You can also delete the heading for a code block ("HTML", "CSS", or "JavaScript"), since these are not used by the live sample macro. -Now that the template has been inserted, we can put in some code, and even some explanatory text. +### Grouping code blocks by heading -### HTML +#### HTML This HTML creates a paragraph and some blocks to help us position and style a message. @@ -109,7 +236,7 @@ This HTML creates a paragraph and some blocks to help us position and style a me ``` -### CSS +#### CSS The CSS code styles the box as well as the text inside it. @@ -129,7 +256,7 @@ The CSS code styles the box as well as the text inside it. } ``` -### JavaScript +#### JavaScript This code is very simple. All it does is attach an event handler to the "Hello world!" text that makes an alert appear when it is clicked. @@ -140,15 +267,57 @@ el.onclick = function () { }; ``` -### Result +#### Result + +Here is the result of running the code blocks above via `\{{EmbedLiveSample('grouping_code_blocks_by_heading')}}`: + +{{EmbedLiveSample('grouping_code_blocks_by_heading')}} + +Here is a link that results from calling these code blocks via `\{{LiveSampleLink('grouping_code_blocks_by_heading', 'Live sample demo link')}}`: + +{{LiveSampleLink('grouping_code_blocks_by_heading', 'Live sample demo link')}} + +### Grouping code blocks by identifier + +This HTML creates a paragraph and some blocks to help us position and style a message. + +```html live-sample___hello-world +

A simple example of the live sample system in action.

+
+
Hello world! Welcome to MDN
+
+``` + +The CSS code styles the box as well as the text inside it. + +```css live-sample___hello-world +.box { + width: 200px; + border-radius: 6px; + padding: 20px; + background-color: #ffaabb; +} + +#item { + font-weight: bold; + text-align: center; + font-family: sans-serif; + font-size: 1.5em; +} +``` -Here is the result of running the code blocks above via `\{{EmbedLiveSample('Live_sample_demo')}}`: +This code attaches an event handler to the "Hello world!" text that makes an alert appear when it is clicked. -{{EmbedLiveSample('Live_sample_demo')}} +```js live-sample___hello-world +const el = document.getElementById("item"); +el.onclick = function () { + alert("Owww, stop poking me!"); +}; +``` -Here is a link that results from calling these code blocks via `\{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}}`: +The result of running the code blocks above via `\{{EmbedLiveSample('hello-world')}}`: -{{LiveSampleLink('Live_sample_demo', 'Live sample demo link')}} +{{EmbedLiveSample("hello-world")}} ## Conventions regarding live samples From 3b1526c8f2aa2afc09ccfd7f32f1253346d15d81 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 17 Nov 2023 10:58:41 +0100 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Dipika Bhattacharya --- .../page_structures/live_samples/index.md | 43 ++++++++++--------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md index 8513cb0923c89a1..83aa07976fddf78 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md @@ -6,9 +6,11 @@ page-type: mdn-writing-guide {{MDNSidebar}} -MDN supports turning code blocks in articles into running samples the reader can see in action. These are called _live samples_ and allows users to see what code output looks like. It also makes documentation dynamic and instructive. +MDN supports displaying code blocks within the articles as _live samples_, enabling readers to see both the code and its output as it would look on a web page. This feature allows readers to understand exactly what the executed code would produce, making the documentation dynamic and instructive. -These live samples can include HTML, CSS, and JavaScript in any combination. Note that "live" samples are _not interactive_; however, they do ensure that the output for a sample matches the source of the sample exactly, because the generated samples run the code in the page directly. +The live sample system can process code blocks written in HTML, CSS, and JavaScript, regardless of the order in which they are written in the page. This ensures that the output corresponds to the combined source code because the system runs the code directly within the page. + +> **Note:** "Live samples" are _not interactive_. ## How does the live sample system work? @@ -18,7 +20,7 @@ A live sample consists of two parts: - One or more code blocks grouped together - A macro call that shows the result of the combined code blocks in an {{HTMLElement("iframe")}} -Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#example_code_blocks) containing code for the sample has a language identifier on it that indicates whether it's HTML, CSS, or JavaScript code; these are `html`, `css`, and `js`. The language classes must be on the corresponding blocks of code and a macro call must be present in the page to display the sample: +Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#example_code_blocks) containing code for the output has a language identifier — `html`, `css`, or `js` — that specifies whether it's HTML, CSS, or JavaScript code. The language classes must be on the corresponding blocks of code, and a macro call (`EmbedLiveSample`) must be present in the page to display the output: ````md ## Examples @@ -33,16 +35,15 @@ Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#examp \{{EmbedLiveSample("Examples")}} ```` - +The live sample system allows grouping of code blocks in different ways to effectively display the output. The next section describes these methods. ### Grouping code blocks Code blocks can be grouped in two ways: -1. Using the ID of a heading or a block element that contains the code blocks -2. Using a string identifier in code blocks +1. Using the ID of a heading or a block element that contains the code blocks as the identifier +2. Specifying a string identifier along with code blocks -Code blocks that do not use an explicit identifier are grouped together using the ID of the heading or block element that contains the code blocks. -The identifier in this case is the ID of a heading or a block element (such as a {{HTMLElement("div")}}), for example: +Code blocks that do not explicit specify an identifier are, by default, grouped together using the ID of the heading or block element that contains the code blocks. The identifier in this case is the ID of a heading or a block element (such as a {{HTMLElement("div")}}). This is shown in the example below, where `html` and `css` codes within the block "Styling a paragraph" are used to generate the output for the `EmbedLiveSample` macro call. ````md ## Examples @@ -77,7 +78,7 @@ Only the `

` element with `class="fancy"` will get styled `red`. - If the ID belongs to a block element, the group includes all the code blocks within the enclosing block element whose ID is used. - If the ID belongs to a heading, the group includes all the code blocks that are after that heading and before the next heading of the same heading level. Note that code blocks under subheadings of the specified heading are all used; if this is not the effect you want, use an ID on a block element or use a string identifier instead. -To group code blocks using a string identifier, add the identifier to the code blocks as a class after the language identifier in the form `live-sample___{IDENTIFIER}`, for example, `live-sample___color-picker`. +To group code blocks using a string identifier, add a class that begins with `live-sample___` to the code block's language identifier. Add a unique identifier to the class prefix in the format `live-sample___{IDENTIFIER}`. The `live-sample___` prefix along with the identifier helps the live sample system recognize and group code blocks correctly. For example, `live-sample___color-picker` uses `color-picker` as the identifier following the `live-sample___` prefix. The following example groups a CSS and a JavaScript code block together using the identifier `color-picker`: ````md @@ -104,9 +105,9 @@ Only the `

` element with `class="fancy"` will get styled `red`: \{{EmbedLiveSample("paragraph-styling")}} ```` -The macro uses a special URL to fetch the sample code for a given group, for example `https://yari-demos.prod.mdn.mozit.cloud/en-US/docs/Web/CSS/animation/_sample_.Cylon_Eye.html`. The general structure is `https://url-of-page/_sample_.group-id.html`, where `group-id` is the ID of the heading or block where the code is located. +The macro uses a special URL to fetch the output for a given group of code blocks, for example `https://yari-demos.prod.mdn.mozit.cloud/en-US/docs/Web/CSS/animation/_sample_.Cylon_Eye.html`. The general structure followed is `https://url-of-page/_sample_.group-id.html`, where `group-id` is the ID of the heading or block where the code blocks are located. -The resulting frame (or page) is sandboxed, secure, and technically may do anything that works on the Web. Of course, as a practical matter, the code must contribute to the point of the page that contains it; random stuff running on MDN will be removed by the editor community. +The resulting frame (or page) is sandboxed, secure, and technically may do anything that works on the web. Of course, as a practical matter, the code should be relevant to the page's content; any unrelated material is subject to removal by MDN's editor community. The live sample system has lots of options available, and we'll try to break things down to look at them one bit at a time. @@ -127,7 +128,7 @@ In many cases, you may be able to add the `EmbedLiveSample` or `LiveSampleLink` - sample_id - : Required: This can be the string identifier of the sample or the ID of the heading or enclosing block to draw the code from. - To verify if you have the correct heading ID is to look at the URL of the section in the page's table of contents; you can also check it by viewing the source of the page. + To verify if you have the correct heading ID, look at the URL of the section in the page's table of contents; you can also check it by viewing the source of the page. - width - : The width of the {{HTMLElement("iframe")}} to create, specified in `px`. This is optional; a reasonable default width will be used if you omit this. Note that if you want to use a specific width, you _must_ also specify the height parameter. - height @@ -168,13 +169,13 @@ Write the code blocks in the respective subsections listed above. In the **Result** subsection, add the call to the `EmbedLiveSample` macro. Preferably, include some more prose in this subsection to describe the result. -If you're not using a particular language type (for example, if you are not using JavaScript) or if you are hiding it, then you should omit the corresponding heading. +If you're not using a particular language type (for example, if you are not using JavaScript) or if you are hiding the code block, then you should omit the corresponding heading. -### Hidden code +### Hiding code -Sometimes you just want to display the static code block that is pertinent to the example rendered within a page. However you still need HTML, CSS and JavaScript to render such an example. +Sometimes you just want to display the static code block pertinent to the example rendered within a page. However, you still need the HTML, CSS, and JavaScript code blocks to render such an example. -To achieve this you can hide any code blocks that are not relevant with the `hidden` class. If you do this, omit the `### HTML/CSS/JavaScript` headings for the hidden code blocks. +To achieve this, you can hide any code blocks that are not relevant by using the `hidden` class. If you do this, omit the `### HTML/CSS/JavaScript` headings for the hidden code blocks. Using the example above but hiding the HTML code would look like this: @@ -208,7 +209,7 @@ Only the `

` element with `class="fancy"` will get styled `red`. ### Turning snippets into live samples -One common use case is to take existing code snippets already shown on MDN and turn them into live samples. +One common use case is to take existing code snippets already shown on MDN and turning them into live samples. The first step is to either add code snippets or ensure that existing ones are ready to be used as live samples, in terms of the content and in terms of their markup. The code snippets, taken together, must comprise a complete, runnable example. For example, if the existing snippet shows only CSS, you might need to add a snippet of HTML for the CSS to operate on. Each piece of code must be in a code block, with a separate block for each language, properly marked as to which language it is. Most of the time, this has already been done, but it's always worth double-checking to be sure each piece of code is configured with the correct syntax. This is done with a language identifier on the code block of `language-type`, where _language-type_ is the type of language the block contains, e.g. `html`, `css`, or `js`. @@ -279,7 +280,7 @@ Here is a link that results from calling these code blocks via `\{{LiveSampleLin ### Grouping code blocks by identifier -This HTML creates a paragraph and some blocks to help us position and style a message. +This HTML creates a paragraph and some blocks to help us position and style a message. The `live-sample___hello-world` class has been added to the `html` language identifier for this code block. ```html live-sample___hello-world

A simple example of the live sample system in action.

@@ -288,7 +289,7 @@ This HTML creates a paragraph and some blocks to help us position and style a me ``` -The CSS code styles the box as well as the text inside it. +The CSS code styles the box as well as the text inside it. The `live-sample___hello-world` class has been added to the `css` language identifier for this code block. ```css live-sample___hello-world .box { @@ -306,7 +307,7 @@ The CSS code styles the box as well as the text inside it. } ``` -This code attaches an event handler to the "Hello world!" text that makes an alert appear when it is clicked. +This JavaScript code attaches an event handler to the "Hello world!" text that makes an alert appear when it is clicked. The `live-sample___hello-world` class has been added to the `js` language identifier for this code block as well. ```js live-sample___hello-world const el = document.getElementById("item"); @@ -315,7 +316,7 @@ el.onclick = function () { }; ``` -The result of running the code blocks above via `\{{EmbedLiveSample('hello-world')}}`: +We get this output by running the code blocks above using the string identifier `hello-world` in the `\{{EmbedLiveSample('hello-world')}}` macro call: {{EmbedLiveSample("hello-world")}} From 3b1068e46d852cfefd7ef3422682b83f5a66861b Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 17 Nov 2023 11:00:40 +0100 Subject: [PATCH 3/6] Update files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md --- .../mdn/writing_guidelines/page_structures/live_samples/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md index 83aa07976fddf78..41c96e06a2dd243 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md @@ -36,6 +36,7 @@ Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#examp \{{EmbedLiveSample("Examples")}} ```` The live sample system allows grouping of code blocks in different ways to effectively display the output. The next section describes these methods. + ### Grouping code blocks Code blocks can be grouped in two ways: From fe163b3a606a696c8525d447ad2bc82082e8fbd3 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 17 Nov 2023 11:01:08 +0100 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../writing_guidelines/page_structures/live_samples/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md index 41c96e06a2dd243..87d28a8afcfe31b 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md @@ -35,8 +35,10 @@ Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#examp \{{EmbedLiveSample("Examples")}} ```` + The live sample system allows grouping of code blocks in different ways to effectively display the output. The next section describes these methods. + ### Grouping code blocks Code blocks can be grouped in two ways: From 9828029e967435e61eecc9faf874b8631d4868b7 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 17 Nov 2023 11:02:26 +0100 Subject: [PATCH 5/6] Update files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../mdn/writing_guidelines/page_structures/live_samples/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md index 87d28a8afcfe31b..e24bf7cb1ab992b 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md @@ -38,7 +38,6 @@ Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#examp The live sample system allows grouping of code blocks in different ways to effectively display the output. The next section describes these methods. - ### Grouping code blocks Code blocks can be grouped in two ways: From d2a6da680830dbd7b1cf315e84a6b27ed4010fd2 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Wed, 22 Nov 2023 10:27:16 +0100 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Dipika Bhattacharya --- .../page_structures/live_samples/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md index e24bf7cb1ab992b..89ab100b2b845c9 100644 --- a/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md +++ b/files/en-us/mdn/writing_guidelines/page_structures/live_samples/index.md @@ -20,7 +20,7 @@ A live sample consists of two parts: - One or more code blocks grouped together - A macro call that shows the result of the combined code blocks in an {{HTMLElement("iframe")}} -Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#example_code_blocks) containing code for the output has a language identifier — `html`, `css`, or `js` — that specifies whether it's HTML, CSS, or JavaScript code. The language classes must be on the corresponding blocks of code, and a macro call (`EmbedLiveSample`) must be present in the page to display the output: +Each [code block](/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN#example_code_blocks) containing code for the output has a language identifier — `html`, `css`, or `js` — that specifies whether it's HTML, CSS, or JavaScript code. The language identifiers must be on the corresponding blocks of code, and a macro call (`EmbedLiveSample`) must be present in the page to display the output: ````md ## Examples @@ -45,7 +45,7 @@ Code blocks can be grouped in two ways: 1. Using the ID of a heading or a block element that contains the code blocks as the identifier 2. Specifying a string identifier along with code blocks -Code blocks that do not explicit specify an identifier are, by default, grouped together using the ID of the heading or block element that contains the code blocks. The identifier in this case is the ID of a heading or a block element (such as a {{HTMLElement("div")}}). This is shown in the example below, where `html` and `css` codes within the block "Styling a paragraph" are used to generate the output for the `EmbedLiveSample` macro call. +Code blocks that do not explicitly specify an identifier are, by default, grouped together using the ID of the heading or block element that contains the code blocks. The identifier in this case is the ID of a heading or a block element (such as a {{HTMLElement("div")}}). This is shown in the example below, where `html` and `css` codes within the block "Styling a paragraph" are used to generate the output for the `EmbedLiveSample` macro call. ````md ## Examples @@ -80,7 +80,7 @@ Only the `

` element with `class="fancy"` will get styled `red`. - If the ID belongs to a block element, the group includes all the code blocks within the enclosing block element whose ID is used. - If the ID belongs to a heading, the group includes all the code blocks that are after that heading and before the next heading of the same heading level. Note that code blocks under subheadings of the specified heading are all used; if this is not the effect you want, use an ID on a block element or use a string identifier instead. -To group code blocks using a string identifier, add a class that begins with `live-sample___` to the code block's language identifier. Add a unique identifier to the class prefix in the format `live-sample___{IDENTIFIER}`. The `live-sample___` prefix along with the identifier helps the live sample system recognize and group code blocks correctly. For example, `live-sample___color-picker` uses `color-picker` as the identifier following the `live-sample___` prefix. +To group code blocks using an identifier, add a string in the format `live-sample___{IDENTIFIER}` to the code block's info string. The identifier must be unique to the code blocks you want to group. For example, `live-sample___color-picker` uses `color-picker` as the identifier for the live sample system, and all code blocks with `live-sample___color-picker` in their info string are combined in the live sample. The following example groups a CSS and a JavaScript code block together using the identifier `color-picker`: ````md @@ -177,7 +177,7 @@ If you're not using a particular language type (for example, if you are not usin Sometimes you just want to display the static code block pertinent to the example rendered within a page. However, you still need the HTML, CSS, and JavaScript code blocks to render such an example. -To achieve this, you can hide any code blocks that are not relevant by using the `hidden` class. If you do this, omit the `### HTML/CSS/JavaScript` headings for the hidden code blocks. +To achieve this, you can hide any code blocks that are not relevant by adding the `hidden` info string to the language identifier. If you do this, omit the `### HTML/CSS/JavaScript` headings for the hidden code blocks. Using the example above but hiding the HTML code would look like this: @@ -282,7 +282,7 @@ Here is a link that results from calling these code blocks via `\{{LiveSampleLin ### Grouping code blocks by identifier -This HTML creates a paragraph and some blocks to help us position and style a message. The `live-sample___hello-world` class has been added to the `html` language identifier for this code block. +This HTML creates a paragraph and some blocks to help us position and style a message. The `live-sample___hello-world` string has been added to the `html` language identifier for this code block. ```html live-sample___hello-world

A simple example of the live sample system in action.

@@ -291,7 +291,7 @@ This HTML creates a paragraph and some blocks to help us position and style a me ``` -The CSS code styles the box as well as the text inside it. The `live-sample___hello-world` class has been added to the `css` language identifier for this code block. +The CSS code styles the box as well as the text inside it. The `live-sample___hello-world` string has been added to the `css` language identifier for this code block. ```css live-sample___hello-world .box { @@ -309,7 +309,7 @@ The CSS code styles the box as well as the text inside it. The `live-sample___he } ``` -This JavaScript code attaches an event handler to the "Hello world!" text that makes an alert appear when it is clicked. The `live-sample___hello-world` class has been added to the `js` language identifier for this code block as well. +This JavaScript code attaches an event handler to the "Hello world!" text that makes an alert appear when it is clicked. The `live-sample___hello-world` string has been added to the `js` language identifier for this code block as well. ```js live-sample___hello-world const el = document.getElementById("item");