Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add live sample specification #5773

Closed
wants to merge 3 commits into from
Closed

Add live sample specification #5773

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f66ea3b
Add live sample specification
wbamberg Jun 7, 2021
166e720
Change how to visualise document sections
wbamberg Jun 24, 2021
74e8d70
Show both search scopes
wbamberg Jun 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
181 changes: 181 additions & 0 deletions files/en-us/mdn/contribute/markdown_in_mdn/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,187 @@ <h2>Heading IDs</h2>

<h2>Live samples</h2>

<p>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.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"built into a document" - do you mean document or something else "like code editor" etc?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean https://developer.mozilla.org/en-US/docs/Web/API/Document

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps link then.


<p>To create a live sample, writers use the <code>\{{EmbedLiveSample}}</code> KumaScript macro.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove KumaScript ?


<p>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:</p>

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is overall really clear.

FWIW I found this diagram unhelpul/confusing at this point in the text. Might be better to move it just above the <h3>Examples</h3> heading (and do the associated rewording).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I could see that. I would prefer not to move it later because this idea that headings section the document is fundamental to the algorithm here. But I think Daniel is going to have some suggestions for improving my ASCII art so I am optimistic this will get better :).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wbamberg stop raising expectations! 😆

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, now that I've built the suspense long enough, what do you think of something like this:

Topic (H1)                                🔍 Final search scope
├── Introductory prose content            ┃
│
├── Syntax (H2#Syntax)                    🙅‍♀️ Unsearched
│   ├── Syntax code block                 ┆
│   │                                     ┆
│   ├── Parameters (H3#Parameters)        ┆
│   │   └── Parameters prose content      ┆
│   │                                     ┆
│   └── Return value (H3#Return)          ┆
│       └── Return value prose content    ┆
│
└── Examples (H2#Examples)                🔍 2nd search scope
    └── Short example (H3#Example1)       🔍 1st search scope
        ├── Example prose content         ┃
        ├── Example code block            ┃
        ├── More prose                    ┃
        └── {{EmbedLiveSample}}           ┃

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really like the tree view here, I think it helps a lot to show the nesting. I think I might prefer to have the heading tag first, to make that more obvious, and I'm not sure we need to show the ID as well (since in Markdown it will always be the same, and in fact it looks wrong to have Short example (H3#Example1) here).

I wanted the ASCII art to show just the sections, independent of the search algorithm, at least at first. I thought it would be helpful just to introduce this way of understanding how we can see a document as sectioned by headers, before talking about the algorithm. So I'm less keen on the right hand column here.

Or maybe we could show just the left hand part in the first diagram, and then talk about it, then talk through the algorithm, then have a second diagram showing both parts?

In the right-hand column as well, there is some strangeness between "Final search scope" and "Unsearched". In this document, with our algorithm, the H1 scope, "Introductory prose content", and even "Examples (H2#Examples)" are not searched, because the algorithm finds code blocks under "Short example (H3#Example1)". So it will actually stop there.

If you had this:

Topic (H1)                                
├── Introductory prose content
│
├── Syntax (H2#Syntax)
│   ├── Syntax code block               
│   │                                     
│   ├── Parameters (H3#Parameters)        
│   │   └── Parameters prose content      
│   │                                     
│   └── Return value (H3#Return)          
│       └── Return value prose content    
│
└── Examples (H2#Examples)        
    └── H3 HTML 
        ├── HTML code block            
    └── H3 JavaScript
        ├── JS code block            
    └── H3 Result           
        └── {{EmbedLiveSample}}

...then we would search Examples (H2#Examples) . If we had this weird thing:

Topic (H1)                                
├── Introductory prose content
└── H2 HTML 
|   └── HTML code block   
│
├── Syntax (H2#Syntax)
│   │                                     
│   ├── Parameters (H3#Parameters)        
│   │   └── Parameters prose content      
│   │                                     
│   └── Return value (H3#Return)          
│       └── Return value prose content    
│
└── Examples (H2#Examples)                 
    └── H3 Result           
        └── {{EmbedLiveSample}}

...then you would search the entire document.

I don't think there's any situation in which you would search at the root H1 and not search one of its children, which seems to be implied by "Final search scope" and "Unsearched".

I guess this kind of thing is why it seems helpful to introduce this in parts, describing the sectioning first and then the algorithm.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've had a go at updating this PR kind of along these lines.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think there's any situation in which you would search at the root H1 and not search one of its children, which seems to be implied by "Final search scope" and "Unsearched".

OK, this was a really good exercise. The problem was not with the diagram exactly, but with my understanding of how the algorithm worked. I'm happy with the new diagrams (except for the loss of emoji). ✅

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just pushed 74e8d70, which shows both first and second search scopes. I did try adding the 🔍 but the one for "First search scope" broke the alignment of the | for "Second (final) search scope". I'd be happy to add it if you know a way around that.

The problem was not with the diagram exactly, but with my understanding of how the algorithm worked.

So you were thinking that sibling sections would not get searched, or...? I'm a little worried that the algorithm wasn't clear enough to avoid a misunderstanding, either that the explanation isn't very good or that it's just too hard to understand.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd be happy to add it if you know a way around that.

Don't worry about that. The emoji bit was just some unsuccessful humor

The explanation isn't very good or that it's just too hard to understand.

No, this is not the case! I didn't read the original very closely and applied my own wishful thinking to the algorithm. I think it's a bit permissive for the algorithm to allow cousin sections to be searched. But forbidding cousin sections is a more complex algorithm, both as an implementation and as something to reason about as an author (particularly in a case where you've placed a live sample code block in a cousin section unintentionally).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the description is a lot clearer with this visualisation, so thanks for your comment.

unsuccessful humor

The best kind of humo(u)r :).

I think it's a bit permissive for the algorithm to allow cousin sections to be searched. But forbidding cousin sections is a more complex algorithm, both as an implementation and as something to reason about as an author (particularly in a case where you've placed a live sample code block in a cousin section unintentionally).

Yeah, exactly. I agree on both counts there. Cousin sections would be a weird thing to do and I think it would be very rare. But forbidding it would make the rule harder to understand.

<pre>
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}}
</pre>

<p>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.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe remove this - the treeview above is clear enough it isn't actually needed. All it did was make me wonder if H1 was actually a section, and therefore whether we had 8 or 7 sections.

Copy link
Collaborator

@hamishwillee hamishwillee Jul 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead, you could perhaps summarise the "rule" you detail below. What I mean is a sentence that says something like "The macro determines what HTML and Javascript files to use based on the relative nesting levels of code blocks and the macro"


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

<ol>
<li>Define the <em>immediate section</em> as the most-nested section that directly contains the macro call itself.</li>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a definition of section, separately of the immediate section? It might add a lot of clarity to describe what a section is exactly.

Based on the examples, I think it means the content following a heading, up to but not including the next same-level heading or the end of the page, whichever comes first. Though this raises another question: does this proposal imply that every page will have an H1? Will that be written out in Markdown sources? Or do we have an implicit section for "any content preceding the first H2" or "the entirety of the page, including any content preceding the first heading"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a definition of section, separately of the immediate section? It might add a lot of clarity to describe what a section is exactly.

Based on the examples, I think it means the content following a heading, up to but not including the next same-level heading or the end of the page, whichever comes first.

Almost, but more like "the content following a heading, up to but not including the next same-or-higher-level heading or the end of the page, whichever comes first. "

Though this raises another question: does this proposal imply that every page will have an H1? Will that be written out in Markdown sources? Or do we have an implicit section for "any content preceding the first H2" or "the entirety of the page, including any content preceding the first heading"?

Yari makes the (front matter) title of the page into the H1 heading, and all top-level headings in content are I think expected to be H2.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Almost, but more like "the content following a heading, up to but not including the next same-or-higher-level heading or the end of the page, whichever comes first. "

Right! 👍

Yari makes the (front matter) title of the page into the H1 heading, and all top-level headings in content are I think expected to be H2.

In that case, for authors, there's an implicit H1 (and content that it's a part of of), which we should probably mention so they can understand that the algorithm is about the structure of the HTML page generated out of Markdown?

<li>Look for any code blocks in the immediate section. If you find any, they are the code blocks to use. Stop looking.</li>
<li>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.</li>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Slight ambiguity is that I might think "in immediate section" meaning just at this level, and not at this level and in any subsections of this level. So perhaps "Look for any code blocks in the immediate section (including any sub-sections)"

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note, this is absolutely captured by the example below, so just a minor point.

<li>If you don't find any, repeat (3) until you find code blocks or until you reach the top-level of the document.</li>
<li>If you reached the top level and didn't find any code blocks, this is an error.</li>
<li>If you did find code blocks, build the document and insert the iframe where the macro call was found.</li>
</ol>

<p>For example, in the case above, the macro call is in <code>H3 Result</code>, so we would:
<ol>
<li>look in <code>H2 Examples > H3 Result</code>, and not find any code blocks</li>
<li>go up to <code>H2 Examples</code>, and look there</li>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In support of https://github.com/mdn/content/pull/5773/files#r668347562 perhaps ", and look there" should be ", and look in that section (and all subsections)

<li>find the code blocks in <code>H2 Examples > H3 HTML</code> and <code>H2 Examples > H3 JavaScript</code>, include them in the live sample, and stop looking.</li>
</ol>
</p>

<pre>
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}} | |
</pre>

<h3>Examples</h3>

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

<pre class="brush: html">
&lt;h2&gt;Examples&lt;/h2&gt;

&lt;h3&gt;Example1&lt;/h3&gt;

JS-code-block-1
CSS-code-block-1
\{{EmbedLiveSample}}

&lt;h3&gt;Example2&lt;/h3&gt;

JS-code-block-2
CSS-code-block-2
\{{EmbedLiveSample}}
</pre>

<p>In this page we have 2 live samples:</p>

<ul>
<li>the one under <code>H3#Example1</code> contains <code>JS-code-block-1</code> and <code>CSS-code-block-1</code></li>
<li>the one under <code>H3#Example2</code> contains <code>JS-code-block-2</code> and <code>CSS-code-block-2</code></li>
</ul>

<p>Another common pattern is where the macro call wants to use code blocks in a sibling section:</p>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"the macro call wants to use code blocks" > "the macro call uses code blocks"


<pre class="brush: html">
Copy link
Collaborator

@hamishwillee hamishwillee Jul 13, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW Change from outline style to HTML style example. I prefer consistency (and outline style)

&lt;h2&gt;Examples&lt;/h2&gt;

&lt;h3&gt;Example1&lt;/h3&gt;

&lt;h4&gt;JavaScript&lt;/h4&gt;

JS-code-block-1

&lt;h4&gt;CSS&lt;/h4&gt;

CSS-code-block-1

&lt;h4&gt;Result&lt;/h4&gt;

\{{EmbedLiveSample}}

&lt;h3&gt;Example2&lt;/h3&gt;

&lt;h4&gt;JavaScript&lt;/h4&gt;

JS-code-block-2

&lt;h4&gt;CSS&lt;/h4&gt;

CSS-code-block-2

&lt;h4&gt;Result&lt;/h4&gt;

\{{EmbedLiveSample}}
</pre>

<p>This also produces 2 live samples:</p>

<ul>
<li>the one under <code>H3#Example1&gt;H4#Result</code> contains <code>JS-code-block-1</code> and <code>CSS-code-block-1</code></li>
<li>the one under <code>H3#Example2&gt;H4#Result</code> contains <code>JS-code-block-2</code> and <code>CSS-code-block-2</code></li>
</ul>

<p>This model also means that certain arrangements are not possible. For example:</p>
hamishwillee marked this conversation as resolved.
Show resolved Hide resolved

<pre class="brush: html example-bad">
&lt;h2&gt;Examples&lt;/h2&gt;

JS-code-block-1
CSS-code-block-1
\{{EmbedLiveSample}}

&lt;h3&gt;Example2&lt;/h3&gt;

JS-code-block-2
CSS-code-block-2
\{{EmbedLiveSample}}
</pre>

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

<h3>Discussion reference</h3>

<p>This issue was resolved in <a href="https://github.com/mdn/content/discussions/5803">https://github.com/mdn/content/discussions/5803</a>.</p>

<h2>Inline styles</h2>

<h2>Superscript and subscript</h2>
Expand Down