[Markdown] First draft of Markdown spec #3950

wbamberg · 2021-04-09T00:01:59Z

Here's a first draft of a spec for writing Markdown in MDN.

The idea is that this specifies a baseline (GFM) and we then add extra bits for anything else we need to support. Adding these extra bits would be separate PRs which would close separate issues, like #3483.

However, I included a resolution for #3512 to show what it would look like, and because this seemed like it could be resolved in the way I've written it up here.

So anyway, I'm interested in things like:

whether we think this is going to be adequate in terms of the guidance it gives to writers and implementors.
whether this general approach of landing a draft spec full of holes and then filling the holes in subsequent PRs sounds like a good one (I think it is, since it gives us a place to work these things out).
is the extra stuff highlighting aspects of GFM useful? We could omit it and just ask people to read the spec but it feels like helpful background for some of the later sections.
anything else?

There is also a need for some other spec about how we manage the conversion - how we get from the HTML we have to this Markdown. But since that's more of a project doc that has a limited shelf-life, it seems better to keep is separate. Then this doc can just talk about how things will be in the end state.

github-actions · 2021-04-09T00:04:08Z

Preview URLs

https://pr3950.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Contribute/Markdown_in_MDN

Flaws

URL: /en-US/docs/MDN/Contribute/Markdown_in_MDN
Title: Markdown in MDN
on GitHub

No flaws! 🎉

External URLs

URL: /en-US/docs/MDN/Contribute/Markdown_in_MDN
Title: Markdown in MDN
on GitHub

http://spec.commonmark.org/ (1 time)
https://daringfireball.net/projects/markdown/syntax (1 time)
https://github.github.com/gfm/ (2 times)

hamishwillee · 2021-04-09T00:34:02Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+
+<h3>KumaScript</h3>
+
+<p>Writers will be able to include KumaScript macro calls in prose content:</p>


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

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

What about {{readonlyinline}}?

hamishwillee · 2021-04-09T00:38:14Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+
+<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>


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.

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

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.

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

hamishwillee · 2021-04-09T00:44:46Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+<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>


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

hamishwillee · 2021-04-09T00:46:10Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+<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>


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

I didn't call this out here because that's true of all elements in GFM, and is not specific to tables.

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

hamishwillee · 2021-04-09T00:48:56Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+</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>
+


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

hamishwillee · 2021-04-09T00:56:19Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+
+<h3>Inline styles</h3>
+
+<h3>KumaScript</h3>


Images heading?

Sorry, I don't understand this comment.

hamishwillee · 2021-04-09T01:15:01Z

@wbamberg My 2 bits. Yes to all your questions, at least for now.

This reads as what it is - a spec with some reasoning and justification and comparison. That's good for first author and implementer audience. Later on we should simplify it down to a cheatsheet - e.g. like https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet along with a list of things that we know can't be ported using markdown in our system (I'm thinking some tables - we may need to think up some way to apply per-table styling).

sideshowbarker · 2021-04-09T01:34:38Z

whether we think this is going to be adequate in terms of the guidance it gives to writers and implementors.

Yes

whether this general approach of landing a draft spec full of holes and then filling the holes in subsequent PRs sounds like a good one (I think it is, since it gives us a place to work these things out).

I agree it’s a good approach. In general with pretty much everything we do, I prefer the approach of landing something and than iterating on it over time — rather than blocking on trying to make it problem-free from the get-go.

is the extra stuff highlighting aspects of GFM useful? We could omit it and just ask people to read the spec but it feels like helpful background for some of the later sections.

I think it’s useful to have the info summarized at point-of-use.

anything else?

I’d prefer to have the entire doc written in markdown rather than HTML :)

wbamberg · 2021-04-09T01:37:30Z

I’d prefer to have the entire doc written in markdown rather than HTML :)

The irony of laboriously writing out, in HTML, a document about using Markdown, was not lost on me :)

chrisdavidmills

Nice work @wbamberg ! I've left a few comments for you, but nothing major.

files/en-us/mdn/contribute/markdown_in_mdn/index.html

chrisdavidmills · 2021-04-09T11:01:02Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

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


This implies we'll be regularly including HTML blocks inside MDN markdown content, whereas I thought we were trying to minimize this as much as possible? I don't really get the point of this section, and why we need to include the <div> in the first place.

During the transition to markdown, mixing might be a useful allowance. Though, I would call it out as something that is a temporary allowance.

OK, I can remove this.

chrisdavidmills · 2021-04-09T11:02:18Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+
+<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>


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

files/en-us/mdn/contribute/markdown_in_mdn/index.html

chrisdavidmills · 2021-04-09T11:05:19Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+  <li>GFM won't parse GFM block elements in table cells.</li>
+</ul>
+
+<p>This last means that if you write:</p>


word missing from this sentence?

files/en-us/mdn/contribute/markdown_in_mdn/index.html

jpmedley · 2021-04-09T19:00:25Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

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


During the transition to markdown, mixing might be a useful allowance. Though, I would call it out as something that is a temporary allowance.

files/en-us/mdn/contribute/markdown_in_mdn/index.html

jpmedley · 2021-04-09T19:07:11Z

files/en-us/mdn/contribute/markdown_in_mdn/index.html

+
+<h3>KumaScript</h3>
+
+<p>Writers will be able to include KumaScript macro calls in prose content:</p>


What about {{readonlyinline}}?

Co-authored-by: Joe Medley <[email protected]>

github-actions · 2021-04-09T20:02:30Z

Preview URLs

https://pr3950.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Contribute/Markdown_in_MDN

Flaws

URL: /en-US/docs/MDN/Contribute/Markdown_in_MDN
Title: Markdown in MDN
on GitHub

No flaws! 🎉

External URLs

URL: /en-US/docs/MDN/Contribute/Markdown_in_MDN
Title: Markdown in MDN
on GitHub

http://spec.commonmark.org/ (1 time)
https://daringfireball.net/projects/markdown/syntax (1 time)
https://github.github.com/gfm/ (2 times)

github-actions · 2021-04-09T20:02:53Z

Preview URLs

https://pr3950.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Contribute/Markdown_in_MDN

Flaws

URL: /en-US/docs/MDN/Contribute/Markdown_in_MDN
Title: Markdown in MDN
on GitHub

No flaws! 🎉

External URLs

URL: /en-US/docs/MDN/Contribute/Markdown_in_MDN
Title: Markdown in MDN
on GitHub

http://spec.commonmark.org/ (1 time)
https://daringfireball.net/projects/markdown/syntax (1 time)
https://github.github.com/gfm/ (2 times)

…markdown-spec * origin/draft-markdown-spec: Update files/en-us/mdn/contribute/markdown_in_mdn/index.html

github-actions · 2021-04-09T22:50:06Z

Preview URLs

https://pr3950.content.dev.mdn.mozit.cloud/en-US/docs/MDN/Contribute/Markdown_in_MDN

Flaws

URL: /en-US/docs/MDN/Contribute/Markdown_in_MDN
Title: Markdown in MDN
on GitHub

No flaws! 🎉

External URLs

URL: /en-US/docs/MDN/Contribute/Markdown_in_MDN
Title: Markdown in MDN
on GitHub

http://spec.commonmark.org/ (1 time)
https://daringfireball.net/projects/markdown/syntax (1 time)
https://github.github.com/gfm/ (2 times)

wbamberg · 2021-04-09T22:51:06Z

OK, I pushed some changes which I hope resolve the comments, and asked for clarification on a couple of comments that I didn't understand...

chrisdavidmills

I think I'm happy with this as it stands. We can publish now and iterate later.

chrisdavidmills · 2021-04-12T07:45:49Z

Anyone else got any other significant concerns before we merge?

Will added 2 commits April 8, 2021 16:43

First draft of Markdown spec

eb2a964

Clarify that language ID is for syntax highlighting

1110729

wbamberg requested a review from chrisdavidmills April 9, 2021 00:01

wbamberg requested a review from a team as a code owner April 9, 2021 00:02

hamishwillee reviewed Apr 9, 2021

View reviewed changes

chrisdavidmills requested changes Apr 9, 2021

View reviewed changes

jpmedley reviewed Apr 9, 2021

View reviewed changes

Update files/en-us/mdn/contribute/markdown_in_mdn/index.html

730409d

Co-authored-by: Joe Medley <[email protected]>

Will added 5 commits April 9, 2021 14:49

Show inline KS macros too

225424c

Remove section on using GFM inside HTML blocks

bb0a0b4

Add a missing word

d37a86e

Add full list of language identifiers

afcc818

Merge remote-tracking branch 'origin/draft-markdown-spec' into draft-…

a80e133

…markdown-spec * origin/draft-markdown-spec: Update files/en-us/mdn/contribute/markdown_in_mdn/index.html

chrisdavidmills approved these changes Apr 12, 2021

View reviewed changes

sideshowbarker approved these changes Apr 12, 2021

View reviewed changes

chrisdavidmills merged commit bce1918 into mdn:main Apr 12, 2021

github-actions bot locked as resolved and limited conversation to collaborators Aug 17, 2022

wbamberg deleted the draft-markdown-spec branch October 15, 2022 17:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Markdown] First draft of Markdown spec #3950

[Markdown] First draft of Markdown spec #3950

wbamberg commented Apr 9, 2021

github-actions bot commented Apr 9, 2021

hamishwillee Apr 9, 2021

wbamberg Apr 9, 2021

jpmedley Apr 9, 2021

hamishwillee Apr 9, 2021

wbamberg Apr 9, 2021

hamishwillee Apr 9, 2021

chrisdavidmills Apr 9, 2021

hamishwillee Apr 9, 2021

hamishwillee Apr 9, 2021 •

edited

Loading

wbamberg Apr 9, 2021

hamishwillee Apr 12, 2021

hamishwillee Apr 9, 2021

hamishwillee Apr 9, 2021

wbamberg Apr 9, 2021

hamishwillee commented Apr 9, 2021

sideshowbarker commented Apr 9, 2021

wbamberg commented Apr 9, 2021

chrisdavidmills left a comment

chrisdavidmills Apr 9, 2021

jpmedley Apr 9, 2021

wbamberg Apr 9, 2021

chrisdavidmills Apr 9, 2021

chrisdavidmills Apr 9, 2021

jpmedley Apr 9, 2021

jpmedley Apr 9, 2021

github-actions bot commented Apr 9, 2021

github-actions bot commented Apr 9, 2021

github-actions bot commented Apr 9, 2021

wbamberg commented Apr 9, 2021

chrisdavidmills left a comment

chrisdavidmills commented Apr 12, 2021


		<h3>KumaScript</h3>

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


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

		</pre>

		<p>...then the attempt to write a list in the bottom-right cell will just generate <code><td>* lists aren't</td></code> in the output.</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 three that are going to be important to us.

		<h3>Markdown in HTML blocks</h3>

[Markdown] First draft of Markdown spec #3950

[Markdown] First draft of Markdown spec #3950

Conversation

wbamberg commented Apr 9, 2021

github-actions bot commented Apr 9, 2021

Preview URLs

Flaws

External URLs

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee Apr 9, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee commented Apr 9, 2021

sideshowbarker commented Apr 9, 2021

wbamberg commented Apr 9, 2021

chrisdavidmills left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Apr 9, 2021

Preview URLs

Flaws

External URLs

github-actions bot commented Apr 9, 2021

Preview URLs

Flaws

External URLs

github-actions bot commented Apr 9, 2021

Preview URLs

Flaws

External URLs

wbamberg commented Apr 9, 2021

chrisdavidmills left a comment

Choose a reason for hiding this comment

chrisdavidmills commented Apr 12, 2021

hamishwillee Apr 9, 2021 •

edited

Loading