This document is a work-in-progress draft at the moment.
+ +It's not actually possible, yet, to write MDN documentation using Markdown, so at the moment this document is used to record the decisions we've made about how we will expect Markdown to be written, when it is supported.
+ +This page describes how we use Markdown to write documentation on MDN. We have chosen GitHub-Flavored Markdown (GFM) as a baseline, and added some extensions to support some of the things we need to do on MDN that aren't readily supported in GFM.
+ +The baseline for MDN Markdown is GitHub-Flavored Markdown (GFM): https://github.github.com/gfm/. This means that for anything not otherwise specified in this page, you can refer to the GFM specification. GFM in turn is a superset of CommonMark (http://spec.commonmark.org/).
+ +GFM and CommonMark describe some extensions to the original Markdown description). We'll highlight two that are going to be important to us. + +
In GFM and CommonMark, authors can use "code fences" to demarcate <pre> blocks. The opening code fence may be followed by some text that is called the "info string". From the spec:
++ +The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag.
+
It's permissible for the info string to contain multiple words, like:
+ ++```fee fi fo fum +// some example code +``` ++ +
In GFM (but not CommonMark) there is a syntax for tables: https://github.github.com/gfm/#tables-extension-. We will make use of this but it should be noted that this syntax imposes limitations on the kinds of tables we can write, so in many cases this syntax will not be appropriate and we will need alternative ways of authoring tables.
+ +In particular:
+ +This last point means that if you write:
+ ++-------------------------------------- +| i'm a test | yes i am | +|----------------|-------------------| +| `inline` is ok | * lists aren't | +-------------------------------------- ++ +
...then the attempt to write a list in the bottom-right cell will just generate <td>* lists aren't</td> in the output.
In this section we'll outline ways in which writers will be able to go beyond the syntax defined in the GFM spec.
+ + +bashcpp (for C/C++)csshtmljavajs (for JavaScript)jsonphppythonsqlxmlwasm (for WebAssembly text format)+```js +const greeting = "I will get syntax highlighting"; +``` ++ +
Writers will be able to supply any one of the following additional words, which must come after the language word:
+ +example-good: style this example as a good example (one to follow)example-bad: style this example as a bad example (one to avoid)hidden: don't render this code block in the page. This is for use in live samples.+```js example-good +const greeting = "I'm a good example"; +``` ++ +
Writers will be able to include KumaScript macro calls in prose content:
+ +
+
+The **`margin`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) property sets the [margin area](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model) on all four sides of an element. It is a shorthand for {{cssxref("margin-top")}}, {{cssxref("margin-right")}}, {{cssxref("margin-bottom")}}, and {{cssxref("margin-left")}}.
+
+\{{EmbedInteractiveExample("pages/css/margin.html")}}
+
+The top and bottom margins have no effect on replaced inline elements, such as {{HTMLElement("span")}} or {{HTMLElement("code")}}.
+
+