Skip to content

[Markdown] First draft of Markdown spec #3950

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

Merged
merged 8 commits into from
Apr 12, 2021
Merged

[Markdown] First draft of Markdown spec #3950

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
eb2a964
First draft of Markdown spec
Apr 8, 2021
1110729
Clarify that language ID is for syntax highlighting
Apr 8, 2021
730409d
Update files/en-us/mdn/contribute/markdown_in_mdn/index.html
wbamberg Apr 9, 2021
225424c
Show inline KS macros too
Apr 9, 2021
bb0a0b4
Remove section on using GFM inside HTML blocks
Apr 9, 2021
d37a86e
Add a missing word
Apr 9, 2021
afcc818
Add full list of language identifiers
Apr 9, 2021
a80e133
Merge remote-tracking branch 'origin/draft-markdown-spec' into draft-…
Apr 9, 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
140 changes: 140 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
@@ -0,0 +1,140 @@
---
title: Markdown in MDN
slug: MDN/Contribute/Markdown_in_MDN
tags:
- MDN
---
<div>{{MDNSidebar}}</div>

<div class="notecard warning">

<h4>Warning</h4>

<p>This document is a work-in-progress draft at the moment.</p>

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

</div>

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

<h2>Baseline: GitHub-Flavored Markdown</h2>

<p>The baseline for MDN Markdown is GitHub-Flavored Markdown (GFM): <a href="https://github.github.com/gfm/">https://github.github.com/gfm/</a>. 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 (<a href="http://spec.commonmark.org/">http://spec.commonmark.org/</a>).</p>

<p>GFM and CommonMark describe some extensions to <a href="https://daringfireball.net/projects/markdown/syntax">the original Markdown description</a>). We'll highlight two that are going to be important to us.

<h3>Code fences and info strings</h3>

<p>In GFM and CommonMark, authors can use "code fences" to demarcate <code>&lt;pre&gt;</code> blocks. The opening code fence may be followed by some text that is called the "info string". From the spec:</p>

<blockquote>
<p> 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.</p>
</blockquote>

<p>It's permissible for the info string to contain multiple words, like:</p>

<pre>
```fee fi fo fum
// some example code
```
</pre>

<h3>Tables</h3>

<p>In GFM (but not CommonMark) there is a syntax for tables: <a href="https://github.github.com/gfm/#tables-extension-">https://github.github.com/gfm/#tables-extension-</a>. 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.</p>
Copy link
Collaborator

Choose a reason for hiding this comment

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

FWIW I have never seen a great markdown syntax for tables, in particular tables that support merging adjacent cells. The solution has always been to allow HTML for more complicated tables.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Yeah, I agree. I will have an issue for tables, and I think it's likely we'll end up deciding to use HTML.

Copy link
Collaborator

Choose a reason for hiding this comment

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

IFF we want to use markdown for more tables we could invent a syntax to apply a style to a markdown block. This would allow us to use markdown for a bigger number of tables - ie. with basic styling like "hide the header" and "add a header column". I've seen this approach in reStructured text, but not in markdown systems.

Copy link
Contributor

Choose a reason for hiding this comment

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

I think I agree with this too. markdown table syntax is really horrible, and I think we'll need to resort to HTML here.


<p>In particular:</p>

<ul>
<li>GFM tables must have a header row.</li>
<li>GFM tables may not have a header column.</li>
<li>GFM won't parse GFM block elements in table cells.</li>
Copy link
Collaborator

Choose a reason for hiding this comment

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

But they will parse html in GFM table cells .... though this sux because you have to have the whole table on one line.

Copy link
Collaborator

@hamishwillee hamishwillee Apr 9, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

You can't apply CSS styling in markdown on a per-table basis. You also can't apply particular styling to rows.

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 didn't call this out here because that's true of all elements in GFM, and is not specific to tables.

Copy link
Collaborator

Choose a reason for hiding this comment

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

Fair enough. I only raised it because tables are the only place where I ever feel the need to add styling from whatever the site-wide setting is. So this is "where the lack matters".

</ul>

<p>This last point means that if you write:</p>

<pre>
--------------------------------------
| i'm a test | yes i am |
|----------------|-------------------|
| `inline` is ok | * lists aren't |
--------------------------------------
</pre>

<p>...then the attempt to write a list in the bottom-right cell will just generate <code>&lt;td&gt;* lists aren't&lt;/td&gt;</code> in the output.</p>

Copy link
Collaborator

Choose a reason for hiding this comment

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

FYI only, the "standard" form for a table in markdown (as shown above) looks like a table. This is cool until you have to write one, or modify the content in any column.

There is a simpler syntax which I usually prefer to use because you don't, as an author, have to think too much about the layout at authoring time.

Header 1 | Header2
--- | ---:
I'm a test | yes i am
`inline` is ok | * lists aren't

Which renders as

Header 1 Header2
I'm a test yes i am
inline is ok * lists aren't

Note:

  • You must have the header
  • Colon can be used in the line after header to indicate alignment of the column text


<h2>Extensions to GFM</h2>

<p>In this section we'll outline ways in which writers will be able to go beyond the syntax defined in the GFM spec.</p>


<h3>Example code blocks</h3>

Writers will use code fences for example code blocks. They must specify the language of the code sample using the first word of the info string, and this will be used to provide syntax highlighting for the block. The following words will be supported:

<ul>
<li><code>bash</code></li>
<li><code>cpp</code> (for C/C++)</li>
<li><code>css</code></li>
<li><code>html</code></li>
<li><code>java</code></li>
<li><code>js</code> (for JavaScript)</li>
<li><code>json</code></li>
<li><code>php</code></li>
<li><code>python</code></li>
<li><code>sql</code></li>
<li><code>xml</code></li>
<li><code>wasm</code> (for WebAssembly text format)</li>
</ul>

For example:

<pre>
```js
const greeting = "I will get syntax highlighting";
```
</pre>

<p>Writers will be able to supply any one of the following additional words, which must come after the language word:</p>

<ul>
<li><code>example-good</code>: style this example as a good example (one to follow)</li>
<li><code>example-bad</code>: style this example as a bad example (one to avoid)</li>
<li><code>hidden</code>: don't render this code block in the page. This is for use in live samples.</li>
</ul>

For example:

<pre>
```js example-good
const greeting = "I'm a good example";
```
</pre>

<h3>Notes and warnings</h3>

<h3>Definition lists</h3>

<h3>Tables</h3>

<h3>Heading IDs</h3>

<h3>Live samples</h3>

<h3>Inline styles</h3>

<h3>KumaScript</h3>
Copy link
Collaborator

Choose a reason for hiding this comment

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

Images 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.

Sorry, I don't understand this comment.


<p>Writers will be able to include KumaScript macro calls in prose content:</p>
Copy link
Collaborator

Choose a reason for hiding this comment

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

Might be worth saying that this can be both as a block or inline (otherwise you might assume from example that the macro must be on its own line).

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 thought of this but then struggled to come up with an inline macro other than *xref, and I expect these to disappear eventually. I guess I could have {{optional_inline}}.

Copy link
Collaborator

Choose a reason for hiding this comment

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

What about {{readonlyinline}}?


<pre>

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")}}.

</pre>