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

## 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
| Milk Bread Cheese Cheddar Camembert 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

- C-Based Performance: Fast, native C implementation for optimal performance
- GitHub Compatibility: Implements GitHub’s Markdown extensions for maximum compatibility
- Lightweight: Minimal dependencies and small footprint
- Extensible: Supports various Markdown extensions and custom options
- HTML5 Support: Generates modern HTML5 output with proper semantic markup

## Major Differences from Standard Markdown

### 1. GitHub Flavored Markdown Extensions

Tables

- Full support for GitHub-style tables with alignment options
- Headers, separators, and data rows with proper HTML table structure
- Column alignment using colons (`:`) in separator rows

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

Task Lists

- Support for GitHub-style checkboxes in lists
- Interactive checkboxes (rendered as HTML input elements)
- Both checked and unchecked states supported

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

Strikethrough Text

- Text enclosed in double tildes (`~~`) becomes strikethrough
- Uses HTML `<del>` tags for semantic markup
- Supports multiple tildes for emphasis

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

### 2. Enhanced Code Block Support

Fenced Code Blocks

- Triple backticks (`````) for code blocks
- Language specification for syntax highlighting
- No indentation required (unlike standard Markdown)

    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

- Recognizes URLs without explicit markup
- Handles various URL formats and protocols
- Configurable link safety options

### 4. Advanced List Features

Alphabetic Lists

- Ordered lists with alphabetic markers (a, b, c, etc.)
- Automatic progression through the alphabet
- Proper HTML `<ol type="a">` output

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

Enhanced List Processing

- Better handling of nested lists
- Improved spacing and indentation
- Support for mixed list types

### 5. Footnotes Support

Reference-Style Footnotes

- Automatic footnote numbering
- Reference links with `[^1]` syntax
- Footnote definitions at document end

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

    [^1]: This is the footnote content.

Automatic Footnote Processing

- Generates proper HTML footnote structure
- Links between references and definitions
- Sequential numbering throughout document

### 6. HTML Integration

HTML5 Support

- Full HTML5 tag recognition
- Proper semantic markup generation
- Modern HTML structure and attributes

Raw HTML Blocks

- Support for HTML within Markdown
- Proper escaping and sanitization
- Integration with Markdown syntax

### 7. Enhanced Emphasis Rules

Relaxed Emphasis

- Single underscores (`_`) don’t create emphasis in the middle of words
- Better for documenting code and technical content
- Prevents unwanted emphasis in identifiers

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

Multiple Emphasis Levels

- Support for bold, italic, and combined emphasis
- Consistent with standard Markdown emphasis rules
- Proper HTML output with `<strong>` and `<em>` tags

### 8. Table of Contents Generation

Automatic TOC

- Generates table of contents from headings
- Hierarchical structure based on heading levels
- Configurable TOC generation options

Heading ID Generation

- Automatic ID generation for headings
- Anchor links for easy navigation
- Consistent ID formatting

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

- README files and project documentation
- GitHub Pages and wikis
- Issue and pull request descriptions

Technical Writing

- Code documentation and tutorials
- API documentation
- Technical specifications

Content Management

- Blog posts and articles
- Documentation websites
- Knowledge bases

Collaborative Editing

- Team documentation
- Project planning documents
- Meeting notes and minutes

## Implementation Details

Output Features

- HTML5 semantic markup
- Proper heading hierarchy
- Accessible table structures
- Clean, valid HTML output

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

- GitHub Flavored Markdown Spec
- Discount Library Documentation
- GitHub Markdown Guide
- Markdown Cheat Sheet

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:

- Unambiguous specifications for all Markdown syntax
- Comprehensive test suite to ensure consistent behavior
- Clear precedence rules for conflicting syntax
- Detailed parsing algorithm that can be implemented consistently

## Key Differences from Standard Markdown

### 1. Stricter Parsing Rules

CommonMark enforces more consistent parsing behavior:

Blank Lines Before Block Elements

- CommonMark requires blank lines before headings, blockquotes, and lists
- Standard Markdown often allows these without blank lines

    Text
    # Heading

CommonMark: Requires blank line before heading

Standard Markdown: Often allows without blank line

### 2. List Item Parsing

Indentation Requirements

- CommonMark has specific rules for list item indentation
- Sublists must be indented consistently (typically 4 spaces)
- Standard Markdown implementations vary on this

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

List Continuation

- CommonMark has clear rules for when list items are “loose” vs “tight”
- Loose lists wrap items in `<p>` tags, tight lists don’t

### 3. Code Block Handling

Fenced Code Blocks

- CommonMark standardizes fenced code block syntax with backticks or tildes
- Requires consistent indentation and closing markers

    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

- CommonMark processes links before emphasis
- This affects how nested syntax is interpreted

### 5. Emphasis and Strong Emphasis

Nested Emphasis Rules

- CommonMark has specific algorithms for handling nested `*` and `_` markers
- Prevents ambiguous parsing of complex emphasis patterns

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

Delimiter Processing

- CommonMark uses a “delimiter stack” algorithm for consistent emphasis parsing
- Standard Markdown implementations vary in their approach

### 6. HTML Block Processing

HTML Block Detection

- CommonMark has 7 different types of HTML blocks with specific rules
- Each type has different requirements for start/end conditions

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

### 7. Line Break Handling

Hard Line Breaks

- CommonMark requires two spaces at end of line for hard breaks
- Single line breaks become soft breaks (ignored in HTML)

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

### 8. Entity and Character References

Numeric Character References

- CommonMark supports both decimal and hexadecimal numeric references
- Standard Markdown support varies

    &#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:

- Specification-compliant: Follows the official CommonMark spec exactly
- Test-driven: Passes the official CommonMark test suite
- Extensible: Can be extended with additional features while maintaining compatibility
- Fast: Optimized parsing algorithms for performance

## Resources

- CommonMark Specification
- CommonMark Test Suite
- CommonMark Dingus - Online testing tool
- CommonMark Discussion Forum

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

- Fast and Pure Ruby: Written entirely in Ruby for performance and portability
- Strict Syntax: Provides definite rules and clear specifications
- Enhanced Features: Includes many extensions not found in standard Markdown
- Jekyll Integration: Default Markdown processor for Jekyll static site generator
- Comprehensive: Supports both block-level and span-level elements with extensive customization

## Major Differences from Standard Markdown

### 1. Enhanced Block-Level Elements

Definition Lists

- Kramdown supports definition lists (not in standard Markdown)
- Uses `:` to separate terms from definitions

    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

- Support for mathematical expressions using LaTeX syntax
- Both inline and block math support

    Inline math: $E = mc^2$

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

### 2. Advanced Text Markup

Footnotes

- Full footnote support with automatic numbering
- Reference-style footnotes with `[^1]` syntax

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

    [^1]: This is the footnote content.

Abbreviations

- Support for HTML-style abbreviations
- Automatic expansion of defined abbreviations

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

    This uses HTML and CSS.

Typographic Symbols

- Automatic conversion of common typographic characters
- Smart quotes, em dashes, ellipses, etc.

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

### 3. Attribute Lists and Extensions

Attribute List Definitions (ALDs)

- Define reusable attribute sets
- Support for IDs, classes, and custom attributes

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

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

Inline Attribute Lists (IALs)

- Attach attributes to specific elements
- Both block-level and span-level support

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

Extensions

- Custom extension system for additional functionality
- Built-in extensions for comments and options

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

    {::options key="val" /}

### 4. Enhanced Code Block Support

Language Specification

- Automatic syntax highlighting for fenced code blocks

- Support for many programming languages

      def hello
        puts "Hello, World!"
      end

Standard Code Blocks

- Improved handling of indented code blocks
- Better integration with other block elements

### 5. Stricter Parsing Rules

Line Wrapping

- Support for hard-wrapped content (lazy syntax)
- Clear rules for when line wrapping is allowed
- Not recommended for readability but supported for compatibility

Tab Handling

- Assumes tab stops at multiples of four
- Tabs only allowed at beginning of lines for indentation
- Must not be preceded by spaces

Block Boundaries

- Clear rules for when elements must start/end on block boundaries
- Consistent behavior across different element types

### 6. Advanced Link and Image Support

Automatic Links

- Enhanced automatic link detection
- Better handling of URLs and email addresses

Reference Links

- Improved reference link processing
- Better conflict resolution for multiple definitions

Image Attributes

- Support for image attributes through IALs
- Width, height, alt text, and other HTML attributes

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

### 7. HTML Integration

HTML Blocks

- Better handling of HTML within Markdown
- Support for HTML attributes and processing
- More flexible than standard Markdown HTML handling

HTML Spans

- Inline HTML with attribute support
- Better integration with Markdown syntax

### 8. Mathematical Expressions

Inline Math

- `$...$` syntax for inline mathematical expressions
- LaTeX-compatible syntax

Block Math

- `$$...$$` syntax for block mathematical expressions
- Support for complex equations and formulas

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

- Default processor for Jekyll static site generation
- Excellent for documentation and blog sites

Technical Documentation

- Math support for scientific and technical writing
- Attribute lists for advanced HTML customization

Academic Writing

- Footnote support for citations and references
- Mathematical expressions for formulas and equations

Content Management

- Extensions for custom functionality
- Attribute lists for metadata and styling

## Resources

- Kramdown Syntax Documentation
- Kramdown Converter Documentation
- Jekyll Integration Guide
- Kramdown GitHub Repository

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