Skip to content

Instantly share code, notes, and snippets.

@SphinxKnight

SphinxKnight/structures_MDN.md Secret

Last active August 22, 2017 19:51
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save SphinxKnight/956c3b3bee811c583ee598ec816010de to your computer and use it in GitHub Desktop.
Save SphinxKnight/956c3b3bee811c583ee598ec816010de to your computer and use it in GitHub Desktop.
Download ZIP
Raw
structures_MDN.md

HTML

Structure #1, used for elements' pages

Technical structure

<div>{{HTMLRef}}</div>
<p> element(s) with a short summary</p>
A table <table class="properties"> with 6 rows
<h2>Attributes<h2>
<p> Eventually a paragraph mentioning global attributes</p>
<dl>
    <dt>{{htmlattrdef("attributename")}}</dt>
    <dd>meaning of attribute</dd>
    <dt></dt>
    <dd></dd>
</dl>

<!--  Optional or too much heterogeneous -->
<h2>Other stuff about the element</h2>
<p>blablabl</p>
<h2></h2>
<p></p>

<h2>Examples</h2>
<!-- pre blocks or <p>, inline HTML or {{EmbedLiveSample}} -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->

<h2> Optional notes </h2>
<!-- stuff paragraph(s) or list(s) -->

<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this would be used for the 138 pages regarding HTML elements which means 70% of the HTML section. To check the different articles, one can filter out the pages with the following tags "HTML"+"Reference"+"Element".

Structure #2, used for global attributes' pages

Technical structure

<div>{{HTMLSidebar("Global_attributes")}}</div>
<p>Some paragraphs to describe the attribute </p>

<!-- Might be some examples -->

<h2>Specifications</h2>
<!-- Spec table -->
<h2>Browser compatibility</h2>
<!-- Compat data table -->

<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this would be used for each "global attribute" page (22 in total): 11%. To check the different articles, one can filter out the pages with the following tags "HTML"+"Reference"+"Global attributes"

Structure #3, used for <input type="x"> pages

Technical structure

<div>{{HTMLRef}}</div>
<p>A quick introductory paragraph</p>
<pre>Code sample</pre>
<p>{{EmbedLiveSample()}}</p>
<table> A table with 5 rows </table>

<h2>Value</h2>
<!-- Paragraphs and/or code sample -->

<h2>Using foo bar</h2>
  <p> Paragraphs and h3 headings with a mix of content and examples</p>

<h2>Validation</h2>
<!-- Paragraphs and/or code sample -->

<h2>Examples</h2>
  <p>Paragraphs</p>
  <pre>Code blocks</pre>
  <p>{{EmbedLiveSample}}</p>

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this would be used for 18 pages across the HTML section: 9% To check the different articles, one can filter out the pages with the following tags "HTML"+"Reference"+"Input"+"Element"

Others

Regarding the HTML section, the 18 (9%) pages which are left out are :

CSS

Structure #1, used for properties

Technical structure

<div>{{CSSRef}}</div>
<p>A quick introductory paragraph</p>
<pre class="brush:css no-line-numbers">
  Applied examples for the property (possible values, etc.)
</pre>
<p>{{cssinfo}}</p>

<h2>Syntax</h2>
  <h3>Values</h3>
    <dl>
      <dt>Possible keyword or value type</dt>
      <dd>Explanation about this value</dd>
      <!-- Other dt/dd couples for each value type/keyword -->
    </dl>
  <h3>Formal syntax</h3>
  <pre class="syntaxbox">
    {{csssyntax}}
  </pre>

<h2>Examples</h2>
<!-- Might be a group of 3 <h3> (CSS)/(HTML)/(Result) or might be pre blocks with EmbedLiveSample -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this would be the structure of 337 pages across the CSS section: 43.5% (not counting prefixed properties) To identify the pages, one can use the following tags: "CSS"+"Reference"+("Property" or "CSS Property").

Structure #2, used for pseudo-class

Technical structure

<div>{{CSSRef}}</div>
<p>A quick introductory paragraph</p>
<pre class="brush:css no-line-numbers">
  Applied examples for the pseudo-class
</pre>
<!-- Might be more descriptive paragraph, more detailed than the introduction. -->


<h2>Syntax</h2>
  <pre class="syntaxbox">
    {{csssyntax}}
  </pre>

<h2>Examples</h2>
<!-- <pre> blocks with or without h3 headings, followed by a <p>{{EmbedLiveSample}}</p> -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this would be the structure of around 44 pages across the CSS section: 5.7% (not counting prefixed pseudo-classes). To identify the pages, one can use the following tags: "CSS"+"Reference"+"Pseudo-class".

Structure #3, used for pseudo-elements

Technical structure

<div>{{CSSRef}}</div>
<p>A quick introductory paragraph</p>
<pre class="brush:css no-line-numbers">
  Applied examples for the pseudo-element
</pre>
<!-- Might be more descriptive paragraph, more detailed than the introduction. -->


<h2>Syntax</h2>
  <pre class="syntaxbox">
    {{csssyntax}}
  </pre>

<h2>Examples</h2>
<!-- <pre> blocks with or without h3 headings, followed by a <p>{{EmbedLiveSample}}</p> -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this structure would be applied at least 44 pages (not counting prefixed pseudo-elements): 5.7% of the CSS section. Useful tags combination: "CSS"+"Reference"+"Pseudo-element"

Structure #4, used for CSS data types

Technical structure

<div>{{CSSRef}}</div>
<p>A quick introductory paragraph</p>

<h2>Syntax</h2>
  <p>Some text with some more context</p>
  <h3>Units>
    <dl>
      <dd>Possible unit A</dd>
      <dt>semantics for unit A</dd>
      <!-- Repeat dd/dt pair for each unit -->
    </dl>

<h2>Interpolation</h2> <!-- Optional -->
<p> Paragraph about the rules of interpolation for values of this type</p>

<h2>Examples</h2>
<h3>Examples of valid syntax</h3>
<pre>foo this is valid</pre>
<h3>Examples of invalid syntax</h3>
<pre>bar this is invalid</pre>

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this structure would be applied on 22 pages: 2.8% of the CSS section. Useful tags combination: "CSS"+"Reference"+"CSS Data Type"

Structure #5, used for CSS functions

Technical structure

<div>{{CSSRef}}</div>
<p>A quick introductory paragraph</p>
<pre class="brush:css no-line-numbers">
  Applied examples for the pseudo-class
</pre>
<h2>Syntax</h2>
  <p>Some text with some more context</p>
  <h3>Value</h3>
    <dl>
      <dd>Possible value type A</dd>
      <dt>semantics for value type A</dd>
      <!-- Repeat dd/dt pair for each value -->
    </dl>
  <h3>Formal syntax</h3>
  <pre class="syntaxbox">
    {{csssyntax}}
  </pre>

<h2>Examples</h2>
<!-- <pre> blocks with or without h3 headings, followed by a <p>{{EmbedLiveSample}}</p> -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this should be used for 33 pages of the CSS section: 4.3%. Useful tags combination: "CSS"+"Reference"+"CSS Function"

Structure #6, used for spec "modules"

Technical structure

<div>{{CSSRef}}</div>
<p>Description of the module</p>
<h2>Reference</h2>


<h2>Guides</h2>

<h3>Properties<h3>
<div class="index">
 <ul>
  <li>{{cssxref("propertyFoo")}}</li>
  <!-- Other li's -->
 </ul>
</div>

<h3> Other category of CSS concepts in the spec (like At-Rules / functions / Data type )</h3> <!-- To be repeated for each category -->
<div class="index">
 <ul>
  <li>{{cssxref("theArticle")}}</li>
  <!-- Other l'is -->
 </ul>
</div>

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Useful tag combination: "CSS" + "Reference" + Overview

Others

Regarding the CSS section, around 100 pages (ca. 12.9%) ar left out:

  • @rules articles: there is too much inconsistency at the time to identify a common factor.
  • Guides pages do not share a common structure, their logic is tied to the topic they describe.
  • Tools are a bit special and might not fall into the "wiki" page (i.e. the content is mostly code and not text).
  • Others

JavaScript

Structure #1, used for constructor pages

Technical structure

<div>{{JSRef}}</div>
<p>A short paragraph containing a brief description of the constructor/object</p>

<h2>Syntax</h2>
<pre class="syntaxbox">new Foo(value)</pre>
<h3>Parameters</h3>
    <dl>
      <dt>Argument #1</dt>
      <dd>Explanation about the arguments' role</dd>
      <!-- Other dt/dd couples for each arg. -->
    </dl>

<h2>Description</h2>
<p> More detailed paragraph about the Constructor/concept</p>
<pre> Eventually some code block</pre>

<h2>Properties</h2>
    <dl>
      <dt>Property #1 (in alphabetical order)</dt>
      <dd>Explanation about the property</dd>
      <!-- Other dt/dd couples for each prop. -->
    </dl>
<h2>Methods</h2>
  <dl>
      <dt>Method #1 (in alphabetical order)</dt>
      <dd>Explanation about the method</dd>
      <!-- Other dt/dd couples for each method -->
  </dl>



<h2>Foo instances</h2>
  <p>Sentence about the prototype chain</p>
  <h3>Properties</h3>
    {{page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Foo/prototype', 'Properties')}}
  <h3>Methods</h3>
    {{page('/en-US/docs/Web/JavaScript/Reference/Global_Objects/Foo/prototype', 'Methods')}}

<h2>Examples</h2>
<!-- <pre> blocks with or without h3 headings, followed by a <p>{{EmbedLiveSample}}</p> -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

This represents 80 pages of the JavaScript section (9.1%). Useful tags: not really helpful here since it's not currently enforced. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects$children would be more helpful (use direct subpages)

Structure #2, used for methods and functions

Technical structure

<div>{{JSRef}}</div>
<p>A short paragraph containing a brief description of the method</p>

<h2>Syntax</h2>
<pre class="syntaxbox">Object.method(arg1, arg2...)</pre>
<h3>Parameters</h3>
    <dl>
      <dt>Argument #1</dt>
      <dd>Explanation about the arguments' role</dd>
      <!-- Other dt/dd couples for each arg. -->
    </dl>
<h3>Return value</h3>
<p>A paragraph about what is to be returned from the method</p>
      

<h2>Description</h2><!-- Optional -->
<p>More detailed paragraph about the method if the summary is not enough</p>

<h2>Examples</h2>
<!-- h3 and several examples if necessary -->
<pre class="brush:js">code example</pre>
<!-- No EmbedLiveSample  -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

In theory, this represents around 463 pages of the JavaScript section: 53% Useful tags: "JavaScript"+"Reference"+"Method"

Structure #3, used for properties (data)

Technical structure

<div>{{JSRef}}</div>
<p>A short paragraph containing a brief description of the method</p>
<p>{{js_property_attributes(X,Y,Z)}}</p>
      

<h2>Description</h2><!-- Optional -->
<p>More detailed paragraph about the method if the summary is not enough</p>

<h2>Examples</h2>
<!-- h3 and several examples if necessary -->
<pre class="brush:js">code example</pre>
<!-- No EmbedLiveSample  -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

At least 239 pages across the JavaScript section: 27.4% Useful tags: "JavaScript"+"Reference"+"Property" but no "Prototype"

Structure #4, used for errors

Technical structure

<div>{{jsSidebar("Errors")}}</div>

<h2>Message</h2>
<pre class="syntaxbox"> Examples of error message in different browsers/situations</pre>

<h2>Error type</h2>
<p>{{jsxref("FooError")}}</p>

<h2>What went wrong?</h2>
<p>Explanation of the erroneous situtation</p>
<!-- May include lists -->

<h2>Examples</h2>
<h3>Situation A</h3>
<p>This is a bad case</p>
<pre class="brush:js example-bad">bad syntax/code</pre>
<p>And this is how to solve this</p>
<pre class="brush:js example-good">good syntax/code</pre>
<!-- Repeat h3/p/pre  with different use cases if necessary -->

<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

63 pages across the JavaScript section: 7.2% Useful tags: "JavaScript"+"Errors"

Structure #5, used for statements

Technical structure

<div>{{JSRef}}</div>
<p>A short paragraph containing a brief description of the method</p>
<h2>Syntax</h2>
<pre class="syntaxbox">statement X</pre>
<dl>
<dd>component #1</dd>
<dt>Description of component #1</dt>
<!-- a pair of dd/dt for each "component" of the statement -->
</dl>

<h2>Description</h2>
<p>More detailed paragraph about the method if the summary is not enough</p>
<pre>Might include preformated blocks</pre>

<h2>Examples</h2>
<h3>Use case #1</h3>
<p>Some text descripting use case #1</p>
<pre class="brush:js">code example</pre>
<!-- No EmbedLiveSample  -->
<!-- Repeat h3/p/pre for each use case -->

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

Ideally, this structure should be used for 28 pages across the JavaScript section: 3.2% Useful tags: "JavaScript"+"Reference"+"Statement" URL : https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements$children

Structure #6, used for prototypes' pages

Technical structure

<div>{{JSRef}}</div>
<p>A short paragraph containing a brief description of the prototype</p>
<p>{{js_property_attributes(X,Y,Z)}}</p>
<h2>Description</h2>
<p> More detailed paragraph about the prototype</p>

<h2>Properties</h2>
    <dl>
      <dt>Property #1 (in alphabetical order)</dt>
      <dd>Explanation about the property</dd>
      <!-- Other dt/dd couples for each prop. -->
    </dl>
<h2>Methods</h2>
  <dl>
      <dt>Method #1 (in alphabetical order)</dt>
      <dd>Explanation about the method</dd>
      <!-- Other dt/dd couples for each method -->
  </dl>

<h2>Specifications</h2>
<!-- Spec table -->

<h2>Browser compatibility</h2>
<!-- Compat data table -->


<h2>An optional "See also"</h2>
<ul>
 <li>Other links and elements</li>
</ul>

Examples

Coverage

In theory this structure should be used for 35 pages across the JavaScript section: 4% Useful tags: "JavaScript"+"Prototype" (some pages might have to be filtered out, I used the doc status list and some regexp...)

Others

Around 110 pages (12.6% of the JS section) have not been described here. This includes:

  • Guides and "Concepts" pages: their structure depends on the topic. They are "too" literary.
  • Operators: no "strong" common structure found across those pages
  • "Hub" pages like the landing page and some other "index" pages
  • "New in JavaScript X.Y" pages: I didn't go through those pages
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment