Markdown Guide

Welcome

This is a guide to basic Markdown. Marked also handles MultiMarkdown, GitHub Flavored Markdown, CommonMark, and Kramdown, which add a few extra tricks. For more information on additional flavors, see the tabs in the menu bar above.
You can test out syntax for supported processorsin the Markdown Dingus.

Text

Markdown Result 
This text is *emphasised*.
 This text is emphasised . 
This text is **bold**.
 This text is bold . 
Here's a quote:

> Excellent work, Kip!
 Here's a quote:
Excellent work, Kip!

Links and Images

Markdown Result 
Link to [Google](http://google.com)
 Link to Google . 
You should [email me](mailto:jane@example.com).
 You should email me . 
My email address is <jane@example.com>.
 My email address is jane@example.com . 
![Marked logo](http://marked2app.com/apple-touch-icon-114x114.png)
 The Marked logo

Headings

Markdown Result 
# Large Heading

Large Heading

 
## Medium Heading

Medium Heading

 
### Smaller Heading

Smaller Heading

Lists

Markdown Result 
* Milk
* Bread
* Cheese
    * Cheddar (4 spaces or tab before asterisk)
    * Camembert
- Rice (You can also use - or + instead of *)
  • Milk
  • Bread
  • Cheese
    • Cheddar
    • Camembert
  • Rice
 
1. Milk
2. Bread
3. Cheese
    1. Cheddar (4 spaces or tab before number)
    1. Camembert (It doesn't matter what the numbers are, they'll be sequential when rendered)
4. Rice
  1. Milk
  2. Bread
  3. Cheese
    1. Cheddar
    2. Camembert
  4. Rice

Special

Markdown Result 
A sentence, followed by a rule.

* * *

Another sentence.
 A sentence, followed by a rule.
Another sentence. 
Two \*literal asterisks\*, not to be confused with *emphasis*.
 Two *literal asterisks*, not to be confused with emphasis .

MultiMarkdown

You can choose between MultiMarkdown and Discount (GitHub Flavored Markdown) in the Processor pane of Marked preferences.

Super and Subscript

You can create superscript and subscript using ^ and ~ within blocks of text.

Text^super

Text~sub

Will produce:

Textsuper

Textsub

Tables

| First Header  | Second Header |
| ------------- | ------------- |
| Row 1 Cell 1  | Row 1 Cell 2  |
| Row 2 Cell 1  | Row 2 Cell 2  |

Renders as:

First Header Second Header
Row 1 Cell 1 Row 1 Cell 2
Row 2 Cell 1 Row 2 Cell 2

In the second row of the table, use colons on either end of the row of dashes to indicate alignment for the column:

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ |:---------------:| -----:|
| col 3 is      | some wordy text | $1600 |
| col 2 is      | centered        |   $12 |
| zebra stripes | are neat        |    $1 |

This code will cause the first column to be left-aligned, the second to be centered, and the third to be right-aligned.

Footnotes

Paragraph text with a footnote[^fn]

[^fn]: This is the footnote text.

Renders as:

Paragraph text with a footnote [1]

  1. This is the footnote text.  ↩

You can also create footnotes inline using text[^footnote text] syntax. Note that this will not be compatible with other processors or older versions of MultiMarkdown.

Cross-References

### Section header [myheaderid]

Renders as…

<h3 id="myheaderid">Section header</h3>

…and can be referenced with [link text][myheaderid] , which renders as a link that will jump to the referenced header.

Definition Lists

Apple
: Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
: An american computer company.

Renders as:

Apple
Pomaceous fruit of plants of the genus Malus in the family Rosaceae.
An american computer company.

Fenced Code Blocks

Blocks of text beginning and ending with ``` will be formatted as pre/code blocks. Fenced code blocks must have a blank line before and after them.

You can optionally add a language specifier for syntax highlighting: ```ruby . 

Here's an example:

```
function test() {
  console.log("notice the blank line before this function?");
}
```

Discount GFM Specification

What is Discount GFM?

Discount GFM (GitHub Flavored Markdown) is a C-based Markdown processor that implements GitHub’s extended Markdown syntax. It’s based on the original Discount library but enhanced with GitHub-specific features like tables, task lists, strikethrough text, and automatic URL linking.

Key Characteristics

Major Differences from Standard Markdown

1. GitHub Flavored Markdown Extensions

Tables

| Header 1 | Header 2 | Header 3 |
| :------- | :------: | -------: |
| Left     |  Center  |    Right |
| Aligned  | Aligned  |  Aligned |

Task Lists

- [x] Completed task
- [ ] Pending task
- [x] Another completed task

Strikethrough Text

~~This text is crossed out~~
~~Mistaken text that should be removed~~

2. Enhanced Code Block Support

Fenced Code Blocks

function hello() {
  console.log("Hello, World!");
}
      

**Automatic Language Detection**

- Support for many programming languages
- Proper syntax highlighting when supported
- Fallback to plain text for unsupported languages

### 3. **Automatic URL Linking**

**URL Autolinking**

- Automatic conversion of URLs to clickable links
- Support for http, https, and ftp protocols
- Email addresses automatically converted to mailto links
      
Visit http://example.com for more information.
Contact us at user@example.com

Smart Link Detection

4. Advanced List Features

Alphabetic Lists

a. First item
b. Second item
c. Third item

Enhanced List Processing

5. Footnotes Support

Reference-Style Footnotes

This is a sentence with a footnote[^1].

[^1]: This is the footnote content.

Automatic Footnote Processing

6. HTML Integration

HTML5 Support

Raw HTML Blocks

7. Enhanced Emphasis Rules

Relaxed Emphasis

This is a variable_name that won't be emphasized.
This is _emphasized text_ that will be styled.

Multiple Emphasis Levels

8. Table of Contents Generation

Automatic TOC

Heading ID Generation

Discount GFM vs Other Markdown Flavors

Feature Discount GFM CommonMark Kramdown MultiMarkdown Standard
Tables Yes No Yes Yes No
Strikethrough Yes No No Yes No
Task Lists Yes No No Yes No
Fenced Code Yes Yes Yes Yes No
Math No No Yes Yes No
Footnotes Yes No Yes Yes No
Definition Lists No No Yes Yes No
Abbreviations No No Yes No No
Attribute Lists No No Yes No No
Extensions Limited No Yes Yes No
Typography Basic No Yes No No
Autolinks Yes No No No No
Alphabetic Lists Yes No No No No

Key Advantages of Discount GFM

  1. GitHub Compatibility: Perfect for content that needs to work on GitHub
  2. Performance: Fast C-based implementation
  3. Simplicity: Focused on core GitHub features without complexity
  4. Reliability: Stable, well-tested implementation
  5. Standards Compliance: Follows GitHub’s Markdown specification
  6. Lightweight: Minimal resource usage and dependencies

Common Use Cases

GitHub Documentation

Technical Writing

Content Management

Collaborative Editing

Implementation Details

Output Features

Best Practices

  1. Use Tables Sparingly: Tables are powerful but can be complex to maintain
  2. Leverage Task Lists: Great for project management and documentation
  3. Utilize Autolinks: Let the processor handle URL conversion automatically
  4. Structure with Headings: Use proper heading hierarchy for better TOC generation

Migration from Standard Markdown

Most standard Markdown works with Discount GFM without changes. To take advantage of GFM features:

  1. Add Tables: Convert data into GitHub-style table format
  2. Use Task Lists: Replace bullet points with checkboxes where appropriate
  3. Enable Strikethrough: Use ~~text~~ for crossed-out content
  4. Leverage Autolinks: Remove manual link markup for simple URLs
  5. Structure Headings: Ensure proper heading hierarchy for TOC generation

Resources

This documentation covers Discount GFM as implemented in Marked. For the most current information, always refer to the official GitHub Flavored Markdown specification.

CommonMark Specification

What is CommonMark?

CommonMark is a strongly specified, highly compatible implementation of Markdown. It was created to address the ambiguities and inconsistencies in John Gruber’s original Markdown specification, which led to divergent implementations across different platforms and tools.

Why CommonMark Exists

The original Markdown specification by John Gruber was intentionally ambiguous in many areas, leading to different interpretations by various implementations. This created problems where the same Markdown document would render differently on different platforms (GitHub, StackOverflow, Reddit, etc.).

CommonMark provides:

Key Differences from Standard Markdown

1. Stricter Parsing Rules

CommonMark enforces more consistent parsing behavior:

Blank Lines Before Block Elements

Text
# Heading

CommonMark: Requires blank line before heading

Standard Markdown: Often allows without blank line

2. List Item Parsing

Indentation Requirements

1. First item
   - Sublist item (4 spaces required in CommonMark)
2. Second item

List Continuation

3. Code Block Handling

Fenced Code Blocks

code here


**Indented Code Blocks**

- CommonMark requires blank lines before indented code blocks
- Standard Markdown often allows them without blank lines

### 4. **Link and Image Processing**

**Reference Link Precedence**

- CommonMark has clear rules for which reference definition takes precedence
- Multiple definitions for the same reference are handled consistently


[link1]: /url1
[link1]: /url2
[link1]  <!-- Uses /url2 in CommonMark -->

Link Parsing Order

5. Emphasis and Strong Emphasis

Nested Emphasis Rules

*foo *bar* baz*  <!-- Clear precedence rules in CommonMark -->

Delimiter Processing

6. HTML Block Processing

HTML Block Detection

<div>
This is an HTML block in CommonMark
</div>

7. Line Break Handling

Hard Line Breaks

Line one
Line two  <!-- Two spaces before line break -->

8. Entity and Character References

Numeric Character References

&#8212;  <!-- Decimal -->
&#x2014; <!-- Hexadecimal -->

CommonMark Parsing Algorithm

CommonMark uses a two-phase parsing approach:

Phase 1: Block Structure

  1. Line Processing: Each line is analyzed for block-level markers
  2. Container Blocks: Blockquotes, lists, and other containers are identified
  3. Leaf Blocks: Headings, code blocks, paragraphs are processed
  4. Reference Links: Link definitions are collected for later use

Phase 2: Inline Structure

  1. Inline Processing: Text within blocks is parsed for inline elements
  2. Emphasis Parsing: Uses delimiter stack algorithm for consistent emphasis
  3. Link Resolution: Reference links are resolved using collected definitions
  4. Entity Processing: Character references are converted to actual characters

Benefits of CommonMark

  1. Predictable Behavior: Same input always produces same output
  2. Cross-Platform Compatibility: Works consistently across different tools
  3. Comprehensive Testing: Extensive test suite ensures reliability
  4. Clear Documentation: Detailed specification eliminates guesswork
  5. Future-Proof: Well-defined extension points for new features

CommonMark vs Other Markdown Flavors

Feature CommonMark GitHub Flavored MultiMarkdown Standard
Tables No Yes Yes No
Strikethrough No Yes Yes No
Task Lists No Yes Yes No
Fenced Code Yes Yes Yes No
Math No Yes Yes No
Footnotes No No Yes No

Implementation Notes

CommonMark is designed to be:

Resources

This documentation covers CommonMark 0.31.2 (2024–01–28). For the most current information, always refer to the official specification.

Kramdown Specification

What is Kramdown?

Kramdown is a fast, pure-Ruby Markdown-superset converter that extends the original Markdown syntax with features found in other implementations like Maruku, PHP Markdown Extra, and Pandoc. It provides a strict syntax with definite rules while maintaining compatibility with most Markdown documents.

Key Characteristics

Major Differences from Standard Markdown

1. Enhanced Block-Level Elements

Definition Lists

Term 1
: Definition 1

Term 2
: Definition 2a
: Definition 2b

Tables

kramdown supports a syntax for creating simple tables. A line starting with a pipe character (|) starts a table row. However, if the pipe characters is immediately followed by a dash (-), a separator line is created. Separator lines are used to split the table header from the table body (and optionally align the table columns) and to split the table body into multiple parts. If the pipe character is followed by an equal sign (=), the tables rows below it are part of the table footer.

| A simple | table |
| with multiple | lines|

With headers and footer

| Header1 | Header2 | Header3 |
|:--------|:-------:|--------:|
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
|----
| cell1   | cell2   | cell3   |
| cell4   | cell5   | cell6   |
|=====
| Foot1   | Foot2   | Foot3
{: rules="groups"}

Without alignment row

|  Header1 |  Header2 |  Header3 |
|  cell1 |  cell2 |  cell3 |   | |
|  cell4 |  cell5 |  cell6 |
|  cell1 |  cell2 |  cell3 |
|  cell4 |  cell5 |  cell6 |
|  Foot1 |  Foot2 |  Foot3 |

Math Blocks

Inline math: $E = mc^2$

Block math:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

2. Advanced Text Markup

Footnotes

This is a sentence with a footnote[^1].

[^1]: This is the footnote content.

Abbreviations

*[HTML]: HyperText Markup Language
*[CSS]: Cascading Style Sheets

This uses HTML and CSS.

Typographic Symbols

"Smart quotes" and -- em dashes -- and ... ellipses

3. Attribute Lists and Extensions

Attribute List Definitions (ALDs)

{:ref-name: #myid .my-class title="My Title"}

A paragraph with attributes.
{: #para-one .highlight}

Inline Attribute Lists (IALs)

This *is*{:.underline} some `code`{:#id}{:.class}.
A [link](test.html){:rel='something'} and some **tools**{:.tools}.

Extensions

{::comment}
This text is completely ignored by kramdown.
{:/comment}

{::options key="val" /}

4. Enhanced Code Block Support

Language Specification

Standard Code Blocks

5. Stricter Parsing Rules

Line Wrapping

Tab Handling

Block Boundaries

6. Advanced Link and Image Support

Automatic Links

Reference Links

Image Attributes

![Alt text](image.jpg){:width="300" height="200" class="responsive"}

7. HTML Integration

HTML Blocks

HTML Spans

8. Mathematical Expressions

Inline Math

Block Math

Kramdown vs Other Markdown Flavors

Feature Kramdown CommonMark GitHub Flavored MultiMarkdown Standard
Tables Yes No Yes Yes No
Strikethrough No No Yes Yes No
Task Lists No No Yes Yes No
Fenced Code Yes Yes Yes Yes No
Math Yes No Yes Yes No
Footnotes Yes No No Yes No
Definition Lists Yes No No Yes No
Abbreviations Yes No No No No
Attribute Lists Yes No No No No
Extensions Yes No No No No
Typography Yes No No No No

Key Advantages of Kramdown

  1. Comprehensive Feature Set: Includes many extensions not found in other implementations
  2. Jekyll Integration: Seamless integration with Jekyll static site generator
  3. Ruby Ecosystem: Pure Ruby implementation with good Ruby tooling support
  4. Extensibility: Custom extension system for additional functionality
  5. Attribute Support: Rich attribute system for HTML output customization
  6. Mathematical Support: Built-in support for LaTeX math expressions
  7. Strict Parsing: Clear, unambiguous parsing rules

Common Use Cases

Jekyll Sites

Technical Documentation

Academic Writing

Content Management

Resources

Migration from Standard Markdown

Most standard Markdown documents work with Kramdown without modification. To take advantage of Kramdown’s features:

  1. Add Definition Lists: Convert glossaries and term lists
  2. Use Attribute Lists: Add IDs, classes, and custom attributes
  3. Implement Footnotes: Convert parenthetical references
  4. Add Math Support: Include mathematical expressions
  5. Use Extensions: Add custom functionality as needed

Best Practices

  1. Avoid Lazy Syntax: Don’t rely on hard-wrapping for readability
  2. Use Attribute Lists: Leverage IALs for styling and metadata
  3. Consistent Indentation: Use spaces instead of tabs when possible

This documentation covers Kramdown 2.5.1. For the most current information, always refer to the official documentation at kramdown.gettalong.org.