Markdown Reference

This document is the comprehensive reference for Markdown support in RDoc. It covers all syntax, extensions, and formatting options available.

For Ruby-specific features that require actual code (like cross-reference targets and directives that only work in Ruby comments), see RDoc::Example.

About the Examples

• Examples show Markdown syntax.

• Rendered output is shown in blockquotes where helpful.

Blocks

Markdown documents consist of various block types:

• Paragraphs: ordinary text blocks.

• Headings: section titles.

• Code Blocks: verbatim text with syntax highlighting.

• Blockquotes: quoted passages.

• Lists: bullet, numbered, and definition lists.

• Tables: tabular data.

• Horizontal Rules: visual separators.

Paragraphs

A paragraph is one or more consecutive lines of text, separated from other blocks by blank lines.

Example:

This is the first paragraph. It can span
multiple lines.

This is the second paragraph.

Single newlines within a paragraph become spaces in the output.

Headings

ATX-Style Headings

Use # characters at the start of a line. Levels 1-6 are supported:

# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6

Optional closing # characters are allowed:

## Heading ##

Setext-Style Headings

Underline text with = for level 1 or - for level 2:

Heading Level 1
===============

Heading Level 2
---------------

Code Blocks

Indented Code Blocks

Indent code by 4 spaces or 1 tab:

This is a paragraph.

    def hello
      puts "world"
    end

This is another paragraph.

Fenced Code Blocks

Use triple backticks with an optional language identifier:

```ruby
def hello
  puts "world"
end
```

Supported language for syntax highlighting: ruby, rb (alias to ruby), and c.

Blockquotes

Prefix lines with >:

> This is a blockquote.
> It can span multiple lines.
>
> Multiple paragraphs are supported.

Blockquotes can contain other elements:

> ## Heading inside blockquote
>
> - List item 1
> - List item 2
>
> Code inside blockquote:
>
>     def example
>       :ok
>     end

Nested blockquotes:

> Outer quote
>
> > Nested quote

Lists

Bullet Lists

Use *, +, or - followed by a space:

* Item 1
* Item 2
* Item 3

Or:

- Item 1
- Item 2
- Item 3

Numbered Lists

Use digits followed by . and a space:

1. First item
2. Second item
3. Third item

The actual numbers don’t matter; they’re renumbered in output:

1. First
1. Second
1. Third

Nested Lists

Indent with 4 spaces to nest:

* Item 1
    * Nested item A
    * Nested item B
* Item 2
    1. Numbered nested
    2. Also numbered

Definition Lists

Use a term on one line, then : followed by the definition:

term
:   Definition of the term.

cat
:   A small furry mammal.

ant
:   A little insect.

Multiple definitions for one term:

apple
:   A fruit
:   A technology company

Tables

Create tables with pipes and dashes:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Column Alignment

Use colons to specify alignment:

| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| Left     | Center   | Right    |
| aligned  | aligned  | aligned  |

• :--- or --- for left alignment (default)

• :---: for center alignment

• ---: for right alignment

Tables support inline formatting in cells:

| Feature     | Syntax          |
|-------------|-----------------|
| **Bold**    | `**text**`      |
| *Italic*    | `*text*`        |
| `Code`      | `` `text` ``    |

Horizontal Rules

Use three or more -, *, or _ on a line by themselves:

---

* * *

___

Text Markup

Inline text can be formatted with various markup:

• Italic: emphasized text.

• Bold: strong emphasis.

• Bold and Italic: combined emphasis.

• Strikethrough: deleted text.

• Inline Code: monospace text.

Italic

Use single asterisks or underscores:

This is *italic* text.
This is _also italic_ text.

This is italic text. This is also italic text.

Note: Underscores within words are not interpreted as emphasis:

foo_bar_baz remains plain text

Bold

Use double asterisks or underscores:

This is **bold** text.
This is __also bold__ text.

This is bold text. This is also bold text.

Bold and Italic

Use triple asterisks or underscores:

This is ***bold and italic*** text.
This is ___also bold and italic___ text.

This is bold and italic text. This is also bold and italic text.

Strikethrough

Use double tildes:

This is ~~strikethrough~~ text.

This is strikethrough text.

Inline Code

Use backticks:

Use the `puts` method.

Use the puts method.

For code containing backticks, use multiple backticks:

Use `` `backticks` `` in code.

Use `backticks` in code.

Links

Inline Links

[Link text](https://example.com)

Link text

With optional title (title is parsed but not used in RDoc output):

[Link text](https://example.com "Title")

Reference Links

Define a reference, then use it:

[Link text][ref]

[ref]: https://example.com

Implicit reference (link text matches reference):

[Example][]

[Example]: https://example.com

Autolinks

URLs and emails in angle brackets become links:

<https://example.com>
<user@example.com>

example.com user@example.com

Cross-References

Link to RDoc-documented classes, modules, and methods:

[RDoc module](rdoc-ref:RDoc)
[Options class](rdoc-ref:RDoc::Options)
[document method](rdoc-ref:RDoc::RDoc#document)

See rdoc.rdoc for complete cross-reference documentation.

Images

Basic image syntax:

![Alt text](path/to/image.png)

Image as a link:

[![Alt text](image.png)](https://example.com)

Anchor Links

RDoc supports GitHub-style anchor links. You can link to any heading using its anchor, which is the heading text converted to lowercase with spaces replaced by hyphens and special characters removed.

For example:

• Link to Footnotes

• Link to Blockquotes

• Link to Anchor Links

Footnotes

Reference Footnotes

Add a footnote reference in text, then define it:

Here is some text[^1] with a footnote[^note].

[^1]: This is the first footnote.
[^note]: This is another footnote.

Inline Footnotes

Create footnotes inline:

Here is text ^[with an inline footnote].

Footnotes are collected and rendered at the bottom of the section, separated by a horizontal rule.

HTML

Block HTML

Raw HTML blocks are preserved:

<div class="note">
  <p>This is HTML content.</p>
</div>

Supported block-level tags include: <address>, <blockquote>, <div>, <fieldset>, <form>, <h1>-<h6>, <ol>, <p>, <pre>, <table>, <ul>.

Inline HTML

Inline HTML is also preserved:

This has <b>bold</b> and <em>emphasized</em> HTML.

Special Characters

Escaping

Use backslash to escape special characters:

\*not italic\*
\`not code\`
\[not a link\]
\# not a heading

Escapable characters: ` \ : | * _ { } [ ] ( ) # + . ! > < -

HTML Entities

Named, decimal, and hexadecimal entities are supported:

© — π
A A

Line Breaks

End a line with two or more spaces for a hard line break:

Line one
Line two

Directives

RDoc directives work in Markdown files within Ruby comments. Use the :markup: markdown directive to specify Markdown format.

# :markup: markdown

# This class uses **Markdown** for documentation.
#
# ## Features
#
# - Bold with `**text**`
# - Italic with `*text*`
class MyClass
end

Common directives (same as RDoc markup):

• :nodoc: - Suppress documentation

• :doc: - Force documentation

• :stopdoc: / :startdoc: - Start/stop documentation parsing

• :call-seq: - Custom calling sequence

• :section: - Create documentation sections

See rdoc.rdoc for complete directive documentation.

Comparison with RDoc Markup

Notes and Limitations

1. Link titles are parsed but not used - The title in [text](url "title") is ignored.

2. Underscores in words - foo_bar is never italicized; emphasis requires whitespace boundaries.

3. Footnotes are collapsed - Multiple paragraphs in a footnote become a single paragraph.

4. Syntax highlighting - Only ruby and c are supported for fenced code blocks.

5. Fenced code blocks - Only triple backticks are supported. Tilde fences (~~~) are not supported as they conflict with strikethrough syntax. Four or more backticks for nesting are also not supported.

6. Auto-linking - RDoc automatically links class and method names in output, even without explicit link syntax.

Comparison with GitHub Flavored Markdown (GFM)

This section compares RDoc’s Markdown implementation with the GitHub Flavored Markdown Spec (Version 0.29-gfm, 2019-04-06).

Block Elements

HTML Blocks

GFM defines 7 types of HTML blocks:

RDoc uses a whitelist of block-level tags defined in lib/rdoc/markdown.kpeg (see HtmlBlockInTags). HTML5 semantic elements like <article>, <section>, <nav>, <header>, <footer> are not supported.

Inline Elements

GFM Extensions

GFM Extended Autolinks

GFM automatically converts certain text patterns into links without requiring angle brackets (<>). RDoc requires the standard <url> syntax.

GFM recognizes these patterns as autolinks:

• www.example.com — text starting with www. followed by a valid domain

• https://example.com — URLs starting with http:// or https://

• user@example.com — valid email addresses

• mailto:user@example.com — mailto: or xmpp: followed by an email

Example in GFM:

Visit www.example.com or contact support@example.com for help.

In GFM, both become clickable links. In RDoc, you must use:

Visit <https://www.example.com> or contact <support@example.com> for help.

RDoc-Specific Features (not in GFM)

• Definition Lists

• Footnotes

• Cross-references

• Anchor Links

• Directives