The Markdown textual content format makes it straightforward for individuals—not solely software program builders however anybody with a keyboard—to write down textual content that may be transformed readily into HTML or one other wealthy format. What’s particular about Markdown is it makes use of plain-text syntax for formatting, so it’s straightforward to inform at a look what Markdown-formatted textual content may appear like when it’s rendered.
Markdown’s general ease of use and ease have led to broad adoption in lots of areas. Bloggers had been the unique use case, utilizing it to write down their posts and adorn them with hyperlinks or markup without having a WYSIWYG editor. Many builders use Markdown or one other variant to write down their documentation. All anybody must get began is a textual content editor.
The historical past of Markdown
Expertise blogger John Gruber, keeper of the Apple-centric weblog daringfireball.web, created Markdown in 2004 in collaboration with Aaron Swartz.
E-mail and USENET posts written in plain textual content had lengthy had their very own tradition of advert hoc formatting, corresponding to utilizing *asterisks* or _underscores_ for emphasis. However these textual hints weren’t rendered as HTML; they simply supplied a visible suggestion of what the markup may appear like. Gruber and Swartz took issues a step additional by utilizing that sort of plain-text markup to generate formatted output. The collaborators additionally took inspiration from the reStructuredText language, which was launched in 2002 or so.
Markdown’s first incarnation was a Perl script that may very well be used standalone or built-in into different software program, corresponding to a weblog’s publishing pipeline or a textual content filter for a message board like BBEdit. It nonetheless exists on this format, however numerous different languages now have Markdown libraries.
Primary Markdown syntax
Markdown paperwork are primarily plain textual content. They are often ASCII or UTF-8, as all of the essential formatting is ASCII. To generate formatted output, you merely feed the Markdown doc right into a processor script, just like the Perl script I discussed above.
Plain textual content renders as-is, however sure character sequences trigger textual content to be formatted both as block or inline components.
That is plain textual content.
Single line breaks are handled as regular whitespace, whereas double line breaks point out a paragraph break:
These two strains
could be thought of a single paragraph.
This double-linebreak separated part could be its personal paragraph.
For textual content emphasis, you should utilize asterisks and underscores, or different symbols:
- Italics:
*Italics* - Daring:
**Daring** - Strikethrough:
~~Strikethrough~~
(Word that the strikethrough syntax is just not universally supported.)
Headers in a doc (the HTML equal of H1 via H5) may be rendered by putting hash marks at first of a line:
# Predominant heading
Textual content
## Subheading
Extra textual content
These would render the next HTML:
Predominant heading
Textual content
Subheading
Extra textual content
To create a horizontal rule, you’d merely kind --- or === on a line by itself.
Inline hyperlinks use a []() building to separate the hyperlink’s textual content and URL, like so:
[the InfoWorld homepage](https://infoworld.com).
Many Markdown variants additionally help an angle-bracket URL format—e.g., —however with out a individually formatted textual content label.
Inserting a picture inline works equally, with a “bang”-prefixed model of a hyperlink: . For simply the picture with no title metadata, use: .
For indented blocks or blockquotes, place a > at first of a paragraph:
Common textual content
> Indented block
>> Double-indented block
Extra common textual content
Code-formatted textual content makes use of blocks fenced off with three backticks:
```
take a look at
```
Unordered lists use *, +, or - to start out a line, with indents used to point ranges:
* Key idea
* Sub-concept
* One other sub-concept
* One other key idea.
For numbering, you should utilize any digit adopted by a interval, because the Markdown renderer will robotically renumber every part:
0. First merchandise
0. Second merchandise
0. Third merchandise
Lastly, you possibly can insert HTML manually if you’d like. Nonetheless, the Markdown renderer could contemplate an space with manually supplied HTML to be exempt from its personal rendering. As an illustration:
This will *not* render as meant.
Some Markdown renderers could attempt to apply Markdown formatting between HTML tags, however others could ignore it. So in some instances, you’d get italics for the above supply, whereas in others you’d get literal asterisks.
No matter what you are attempting to do with Markdown, even a look on the unique, unformatted textual content gives a way of how the formatted product is meant to look.
Use instances for Markdown
The unique use case for Markdown was running a blog. It was an alternate for bloggers or message board customers who needed to render wealthy textual content however keep away from writing HTML by hand (together with HTML-esque variants like BBCode) or utilizing a WYSIWYG editor to generate markup.
Running a blog and textual content posting typically stay widespread purposes for Markdown. Messaging programs like Discord and Slack use Markdown (with some gratuitous modifications) to permit customers to put up wealthy, annotated textual content or embody hyperlinks or photographs.
A standard use case for Markdown is undertaking documentation. A easy README.md is simple to assemble with Markdown, and the usual helps greater than sufficient formatting syntax for such a job. For bigger, extra complicated documentation jobs, Markdown may also suffice, and whereas there’s criticism about how effectively it scales, many documentation instruments, corresponding to Mkdocs, use Markdown as a core format. Varied Markdown-inspired variants (described beneath) add customized options to the Markdown customary to make it extra helpful for producing documentation.
Markdown can be an acceptable base format for a wiki. Wiki formatting usually follows the identical philosophy as Markdown: a plaintext format with annotations that may be visually parsed. Most wiki implementations of Markdown additionally lengthen the usual—for example, to permit transclusion of paperwork, or by utilizing a template for formatting.
Limitations of Markdown
The core Markdown customary (which for a very long time was only a de facto customary) helps solely a small handful of formatting choices. That’s largely a mirrored image of its unique use instances. It wasn’t meant to be a one-to-one HTML-generation device, however a approach to shortly write issues that used the most typical and broadly supported HTML components.
Markdown is a targeted and concise customary, with the tradeoff of many issues being utterly lacking. Listed below are a few of the stuff you can’t render with the core Markdown customary:
- Tables: Varied gratuitous extensions for Markdown help desk formatting, sometimes by utilizing the pipe image (
|) to outline desk columns. Nonetheless, the implementations aren’t constant, and the core Markdown implementation has no desk syntax. - Footnotes or endnotes: Even on a easy webpage, some automated approach to outline footnotes or endnotes in textual content may be helpful. Markdown provides no native manner to do that.
- Metadata or variables: Markdown has no native mechanism for outlining document-level metadata and even inline feedback. A manually inserted HTML remark block may maintain information, however by itself, Markdown has no approach to do something helpful with it; it will simply get transformed to HTML together with every part else, and never essentially stripped from the output.
- Management over CSS lessons or types: When you have a block of textual content you wish to apply a method to, the one approach to do it’s to surround it in HTML tags; e.g.,
Markdown variants to discover
As a result of Markdown is at coronary heart pretty minimal, variations on the unique syntax have sprung up through the years. They weren’t meant to eclipse or exchange Markdown, however to flank it. These variants provide a syntax that begins with Markdown and builds helpful options on high of it.
CommonMark
CommonMark is supposed to be a “strongly outlined, extremely suitable specification of Markdown.” It takes the core Markdown syntax and formalizes it to create a specification, reference implementations, a take a look at suite, and quite a lot of different instruments. It doesn’t outline any extensions on the usual, solely an unambiguous description of it, and methods to create instruments that conform to the usual.
GitHub-Flavored Markdown
A broadly adopted variant of Markdown is GitHub-flavored Markdown, so named each as a result of GitHub developed it and since lots of its options complement use instances on GitHub. The specification expands on CommonMark so as to add tables, task-list objects (for instance, for creating to-do lists), and a mechanism for disabling uncooked HTML tags that may be problematic (corresponding to ).
MultiMarkdown
Like GitHub-Flavored Markdown, the MultiMarkdown undertaking expands on the bottom Markdown syntax however provides options generally utilized in paperwork like scientific papers or books, corresponding to tables, footnotes, citations, cross-references, and LaTeX math formulae.