Markdown is a simple syntax that formats text as headers, lists, boldface, and so on. This markup language is popular, and you definitely have apps that support it. Here’s a quick primer on what Markdown is, and how and where you can use it. Main; Basics; Syntax; License; Dingus; Download. Markdown 1.0.1 (18 KB) — 17 Dec 2004. Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

• Markdown Underline
• Cached
• Github Markdown Guide

What is Markdown?

It’s a plain text format for writing structured documents, based on formatting conventions from email and usenet.

Who created Markdown?

It was developed in 2004 by John Gruber in collaboration with Aaron Swartz. Gruber wrote the first markdown-to-html converter in Perl, and it soon became widely used in websites. By 2014 there were dozens of implementations in many languages.

Why is CommonMark needed?

John Gruber’s canonical description of Markdown’s syntax does not specify the syntax unambiguously.

In the absence of a spec, early implementers consulted the original Markdown.pl code to resolve these ambiguities. But Markdown.pl was quite buggy, and gave manifestly bad results in many cases, so it was not a satisfactory replacement for a spec. Markdown.pl was last updated December 17th, 2004.

Because there is no unambiguous spec, implementations have diverged considerably over the last 10 years. As a result, users are often surprised to find that a document that renders one way on one system (say, a GitHub wiki) renders differently on another (say, converting to docbook using Pandoc). To make matters worse, because nothing in Markdown counts as a “syntax error,” the divergence often isn’t discovered right away.

There’s no standard test suite for Markdown; MDTest is the closest thing we have. The only way to resolve Markdown ambiguities and inconsistencies is Babelmark, which compares the output of 20+ implementations of Markdown against each other to see if a consensus emerges.

We propose a standard, unambiguous syntax specification for Markdown, along with a suite of comprehensive tests to validate Markdown implementations against this specification. We believe this is necessary, even essential, for the future of Markdown.

That’s what we call CommonMark.

Who are you?

We’re a group of Markdown fans who either work at companies with industrial scale deployments of Markdown, have written Markdown parsers, have extensive experience supporting Markdown with end users – or all of the above.

• John MacFarlane, jgm@berkeley.edu
• David Greenspan
• Vicent Marti, vicent@github.com
• Neil Williams, neil@reddit.com
• Benjamin Dumke-von der Ehe
• Jeff Atwood, jatwood@codinghorror.com

How can I help?

Exercise our reference implementations, or find a community implementation in your preferred environment or language. Provide feedback!

If a CommonMark implementation does not already exist in your preferred environment or language, try implementing your own CommonMark parser. One of our major goals is to strongly specify Markdown, and to eliminate the many old inconsistencies and ambiguities that made using Markdown so difficult. Did we succeed?

Where can I find it?

spec.commonmark.org

Markdown Underline

The CommonMark specification.

code.commonmark.org

Reference implementation and validation test suite on GitHub.

talk.commonmark.org

Public discussion area and mailing list via Discourse.

commonmark.org/help

Quick reference card and interactive tutorial for learning Markdown.

spec.commonmark.org/dingus/

Live testing tool powered by the reference implementation.

When is the spec final?

The current version of the CommonMark spec is quite robust after many years of public feedback.

There are currently CommonMark implementations for dozens of programming languages, and the following sites and projects have adopted CommonMark:

• Discourse
• GitHub
• GitLab
• Reddit
• Qt
• Stack Overflow / Stack Exchange
• Swift

In different locations around Hub, you have the ability to format blocks of text. This formatting is applied using the Markdown markup syntax. Markdown is supported for the following features in Hub:

The Markdown implementation in YouTrack follows the CommonMark specification with extensions. These extensions support formatting options that are not included in the formal specification like strikethrough text, tables, and autolinks.

To see any of these formatting options in action, paste the sample block of code into an input field that accepts Markdown.

Character Formatting

You can format inline text with the following Markdown syntax.

Headings

To apply a heading style, start the line with one to six number signs #. Follow the number signs with a space character and enter the heading text. The number of # signs determines the heading level.

Hub also supports an alternative syntax for heading levels 1 and 2:

• For heading level 1, enter one or more = characters on the following line.

• For heading level 2, enter one or more - characters on the following line.

Paragraphs and Line Breaks

Contiguous lines of text belong to the same paragraph. Use the following guidelines to structure your content into paragraphs and enter line breaks.

• To start a new paragraph, leave a blank line between lines of text.

• To start a new line inside a paragraph, enter two trailing spaces at the end of the line of text.

Cached

Thematic Breaks

Create sections in your content with horizontal lines. Use any of the following methods to add a horizontal line:

• Three underscores (___)

• Three minus signs (---)

• Three asterisks (***)

Block Quotes

Use block quotes to call special attention to a quote from another source. You can apply character formatting to inline text inside the quoted block.

To set text as a quote block, start the line with one or more > characters. Follow these characters with a space and enter the quoted text. The number of > signs determines the level of nesting inside the quote block.

If your quote spans multiple paragraphs, each blank line must start with the > character. This ensures that the entire quote block is grouped together.

Indented Code Blocks

You can format blocks of text in a monospaced font to make it easier to identify and read as code.

To format a code block in Markdown, indent every line of the block by at least four spaces. An indented code block cannot interrupt a paragraph, so you must insert at least one blank line between a paragraph the indented code block that follows. The input is processed is as follows:

• One level of indentation (four spaces) is removed from each line of the code block.

• The contents of the code block are literal text and are not parsed as Markdown.

• Any non-blank line with fewer than four leading spaces ends the code block and starts a new paragraph.

Fenced Code Blocks

Unlike indented code blocks, fenced code blocks have an info string that lets you specify which language is used for syntax highlighting. Language-specific highlights make the code easier to read.

Syntax highlighting is supported for a range of languages. YouTrack detects and highlights code in C, C++, C#, Java, JavaScript, Perl, Python, Ruby, and SH automatically. To highlight code in other languages, set the language in the info string (the line with the opening code fence). The following languages are supported: apollo (AGC/AEA Assembly Language), basic, clj (Clojure) css, dart, erlang, hs (Haskell), kt (Kotlin), lisp, llvm, lua, matlab, ml, mumps, n (Nemerle), pascal, proto, scala, sql, tcl, tex, vb, vhdl, wiki, xq, and yaml.

• To create a fenced code block that spans multiple lines of code, set the text inside three or more backquotes (```) or tildes (~~~ ).

• Open and close the block with the same character.

• Use the same number of characters to open and close the code fence.

Lists

Use the following syntax to create lists:

• To create an unordered list, start the line with a dash (- ), asterisk (* ), or plus sign (+ ).

• To create an ordered list, start the line with a number and a period (1. ). Increment subsequent numbers to format each item in the ordered list.

• To nest an unordered list inside an unordered or ordered list, indent the line with two spaces. Nesting ordered lists is not supported.

Tables

Tables are a great tool for adding structure to your content. Use the following syntax to create tables:

• To create columns, use vertical bars (| ). The outer bars are optional.

• Separate the header row from the rest of the table with three or more dashes (--- ).

Note that the columns don't have to line up perfectly in the raw Markdown. You can also add character formatting to text inside the table.

All of the cells are left-justified. The syntax that aligns text to the right or center is not supported.

Links

There are several ways to insert hyperlinks with Markdown.

Hub has also extended the standard syntax to include Autolinks.

URLs and URLs in angle brackets are automatically converted into hyperlinks. For example:

• https://www.jetbrains.com

• <https://www.jetbrains.com>

• jetbrains.com

Autolinks

Autolinks are absolute URIs and email addresses that are set inside angle brackets (< > ). They are parsed as links, with the URL or email address as the link label. Unlike Links that let you specify link text and tooltips, this syntax simply converts the URL or email address into a clickable link.

Hub supports an extended syntax for URLs. Any string that is parsed as a URL is converted into a clickable link, even without the angle brackets. Email addresses that are not set inside angle brackets are displayed as text.

Images

The syntax for images is similar to the syntax for links. To insert an inline image:

• Start the line with an exclamation point (! ).

• Wrap the alt text with brackets ([ ] ).

• Set the image URL and tooltip in parentheses (( ) ).

You can also use the reference style for images. To insert an image reference:

• Start the line with an exclamation point (! ).

• Wrap the alt text with brackets ([ ] ).

• Set the image reference in brackets ([ ] ).

• Define the image reference in another location with the format [tag]: image URL 'tooltip'.

Backslash Escapes

Github Markdown Guide

When you have characters that are parsed as Markdown that you want to show as written, you can escape the character with the backslash ( ).

• Backslashes before non-markup characters are shown as backslash characters.

• Escaped characters are treated as regular characters. Their usual meaning in Markdown syntax is ignored.

• Backslash escapes do not work in fenced code blocks, inline code spans, or autolinks.