CommonMark: A Formal Specification For Markdown

• Dingus permalink to check out the full example with the Preview and AST.
• Learn more about Thematic breaks.

Lists

Lists in Markdown are either a bullet (unordered) list or an ordered list.

The following rules define a list:

1. Bullet lists are rendered in HTML as the Unordered list element,
   .
   • Ordered lists are rendered in HTML as the Ordered list element,
     .
     1. Bullet lists use asterisks, pluses, and hyphens as markers.
     2. Ordered lists use numbers followed by periods or closing parenthesis.
     3. The markers must be consistent (you must only use the marker you begin with for the rest of the list items definition).

     Syntax	Rendered HTML
     * one * two * three	<ul> <li>one</li> <li>two</li> <li>three</li> </ul>
     + one + two + three	<ul> <li>one</li> <li>two</li> <li>three</li> </ul>
     - one - two - three	<ul> <li>one</li> <li>two</li> <li>three</li> </ul>
     - one - two + three	<ul> <li>one</li> <li>two</li> </ul> <ul> <li>three</li> </ul>
     1. one 2. two 3. three	<ol> <li>one</li> <li>two</li> <li>three</li> </ol>
     3. three 4. four 5. five	<ol start="3"> <li>three</li> <li>four</li> <li>five</li> </ol>
     1. one 2. two 3. three	<ol> <li>one</li> <li>two</li> <li>three</li> </ol>

     • Interactive tutorial to learn about lists.
     • Dingus permalink to check out the full example with the Preview and AST.
     • Learn more about Lists items.

     Links

     Links are supported with the inline and reference format.

     The following rules define a link:

     1. Links are rendered as the HTML Anchor element, .
     2. The inline format has the syntax: [value](URL "optional-title") with no space between the brackets.
     3. The reference format has the syntax: [value][id] for the reference, and [id]: href "optional-title" for the hyperlink label, separated with at least a line.
     4. The id is the Definition Identifier and may consist of letters, numbers, spaces, and punctuation.
     5. Definition Identifiers are not case sensitive.
     6. There is also support for Automatic Links, where the URL is bounded by the less than (<) and greater than (>) symbol, and displayed literally.

     <!--Markdown-->
     [Google](https://google.com “Google”)
     <!--Rendered HTML-->
     <a href="https://google.com" title="Google">Google</a>
     
     <!--Markdown-->
     [Google](https://google.com)
     <!--Rendered HTML-->
     <a href="https://google.com">Google</a>
     
     <!--Markdown-->
     [Comparing Styling Methods in Next.js](/2020/09/comparing-styling-methods-next-js)
     <!--Rendered HTML-->
     <a href="/2020/09/comparing-styling-methods-next-js">Comparing Styling Methods In Next.js</a>
     
     <!--Markdown-->
     [Google][id]
     <!--At least a line must be in-between-->
     
     <!--Rendered HTML-->
     <a href="https://google.com" title="Google">Google</a>
     
     <!--Markdown-->
     <https://google.com>
     <!--Rendered HTML-->
     <a href="https://google.com">google.com</a>
     
     <!--Markdown-->
     <mark@google.com>
     <!--Rendered HTML-->
     <a href="mailto:mark@google.com">mark@google.com</a>
     

     • Interactive tutorial to learn about links.
     • Dingus permalink to check out the full example with the Preview and AST.
     • Learn more about Links.

     Images

     Images in Markdown follows the inline and reference formats for Links.

     The following rules define images:

     1. Images are rendered as the HTML image element, .
     2. The inline format has the syntax: ![alt text](image-url "optional-title").
     3. The reference format has the syntax: ![alt text][id] for the reference, and [id]: image-url "optional-title" for the image label. Both should be separated by at least a blank line.
     4. The image title is optional, and the image-url can be relative.

     <!--Markdown-->
     ![alt text](image-url "optional-title")
     <!--Rendered HTML-->
     <img src="image-url" alt="alt text" title="optional-title" />
     
     <!--Markdown-->
     ![alt text][id]
     <!--At least a line must be in-between-->
     <!--Markdown-->
     
     <!--Rendered HTML-->
     <img src="image-url" alt="alt text" title="optional-title" />

     • Interactive tutorial to learn about images.
     • Dingus permalink to check out the full example with the Preview and AST.
     • Learn more about Images.

     Blockquotes

     The HTML Block Quotation element,

     , can be created by prefixing a new line with the greater than symbol (>).

     <!--Markdown-->
     > This is a blockquote element
     > You can start every new line
     > with the greater than symbol.
     > That gives you greater control
     > over what will be rendered.
     
     <!--Rendered HTML-->
     <blockquote>
     <p>This is a blockquote element
     You can start every new line
     with the greater than symbol.
     That gives you greater control
     over what will be rendered.</p>
     </blockquote>

     Blockquotes can be nested:

     <!--Markdown-->
     > Blockquote with a paragraph
     >> And another paragraph
     >>> And another
     
     <!--Rendered HTML-->
     <blockquote>
     <p>Blockquote with a paragraph</p>
     <blockquote>
     <p>And another paragraph</p>
     <blockquote>
     <p>And another</p>
     </blockquote>
     </blockquote>
     </blockquote>

     They can also contain other Markdown elements, like headers, code, list items, and so on.

     <!--Markdown-->
     > Blockquote with a paragraph
     > # Heading 1
     > Heading 2
     > -
     > 1. One
     > 2. Two
     
     <!--Rendered HTML-->
     <blockquote>
     <p>Blockquote with a paragraph</p>
     <h1>Heading 1</h1>
     <h2>Heading 2</h2>
     <ol>
     <li>One</li>
     <li>Two</li>
     </ol>
     </blockquote>

     • Interactive tutorial to learn about blockquotes.
     • Dingus permalink to check out the full example with the Preview and AST.
     • Learn more about Blockquotes.

     Code

     The HTML Inline Code element, , is also supported. To create one, delimit the text with back-ticks (`), or double back-ticks if there needs to be a literal back-tick in the enclosing text.

     <!--Markdown-->
     `inline code snippet`
     <!--Rendered HTML-->
     <code>inline code snippet</code>
     
     <!--Markdown-->
     `<button type='button'>Click Me</button>`
     <!--Rendered HTML-->
     <code><button type='button'>Click Me</button></code>
     
     <!--Markdown-->
     `` There's an inline back-tick (`). ``
     <!--Rendered HTML-->
     <code>There's an inline back-tick (`).</code>

     • Interactive tutorial to learn about code.
     • Dingus permalink to check out the full example with the Preview and AST.
     • Learn more about Code spans.

     Code Blocks

     The HTML Preformatted Text element, <pre>, is also supported. This can be done with at least three and an equal number of bounding back-ticks (`), or tildes (~) — normally referred to as a code-fence, or a new line starting indentation of at least 4 spaces.

     <!--Markdown-->
     ```
     const dedupe = (array) => [...new Set(array)];
     ```
     <!--Rendered HTML-->
     <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>
     
     <!--Markdown-->
         const dedupe = (array) => [...new Set(array)];
     <!--Rendered HTML-->
     <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>

     • Interactive tutorial to learn about code.
     • Dingus permalink to check out the full example with the Preview and AST.
     • Learn more about Fenced and Indented code blocks.

     Using Inline HTML

     According to John Grubers original spec note on inline HTML, any markup that is not covered by Markdown’s syntax, you simply use HTML itself, with The only restrictions are that block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces.

     However, unless you are probably one of the people behind CommonMark itself, or thereabout, you most likely will be writing Markdown with a flavor that is already extended to handle a large number of syntax not currently supported by CommonMark.

     Going Forward

     CommonMark is a constant work in progress with its spec last updated on April 6, 2019. There are a number of popular applications supporting it in the pool of Markdown tools. With the awareness of CommonMark’s effort towards standardization, I think it is sufficient to conclude that in Markdown’s simplicity, is a lot of work going on behind the scenes and that it is a good thing for the CommonMark effort that the formal specification of GitHub Flavored Markdown is based on the specification.

     The move towards the CommonMark standardization effort does not prevent the creation of flavors to extend its supported syntax, and as CommonMark gears up for release 1.0 with issues that must be resolved, there are some interesting resources about the continuous effort that you can use for your perusal.

     Resources

     • Introducing Markdown by John Gruber
     • CommonMark official website
     • GitHub Flavored Markdown Spec
     • cmark official repo
     • GitHub’s fork of cmark
     • Markdown on Wikipedia
     • Markdown Guide

     Further Reading

     • Best Of Pro Scheduler Libraries
     • SVG Coding Examples: Useful Recipes For Writing Vectors By Hand
     • Mastering Typography In Logo Design
     • It’s Time To Talk About “CSS5”

     (ks, ra, yk, il, mrn)

     Explore more on