Skip to content

Add comparison with GitHub Flavored Markdown spec #1550

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
st0012 wants to merge 1 commit into
base: master
Choose a base branch
from
+104 −0
Open

Add comparison with GitHub Flavored Markdown spec #1550

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions doc/markup_reference/markdown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -556,3 +556,107 @@ See [rdoc.rdoc](rdoc.rdoc) for complete directive documentation.
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](https://github.github.com/gfm/) (Version 0.29-gfm, 2019-04-06).

### Block Elements

| Feature | GFM | RDoc | Notes |
|---------|:---:|:----:|-------|
| ATX Headings (`#`) | ✅ | ✅ | Both support levels 1-6, optional closing `#` |
| Setext Headings | ✅ | ✅ | `=` for H1, `-` for H2 |
| Paragraphs | ✅ | ✅ | Full match |
| Indented Code Blocks | ✅ | ✅ | 4 spaces (RDoc also accepts 1 tab) |
| Fenced Code (backticks) | ✅ 3+ | ⚠️ 3 only | RDoc doesn't support 4+ backticks for nesting |
| Fenced Code (tildes) | ✅ `~~~` | ❌ | Conflicts with strikethrough syntax |
| Info strings (language) | ✅ any | ⚠️ `ruby`/`rb`/`c` | Limited syntax highlighting |
| Blockquotes | ✅ | ✅ | Full match, nested supported |
| Lazy Continuation | ✅ | ❌ | GFM allows omitting `>` on continuation lines |
Copy link
Member Author

@st0012 st0012 Jan 6, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RDoc interprets

> foo
bar

as > foo bar due to how ToHtml handles the newline.

I'll try to fix the issue so it matches GFM.

| Bullet Lists | ✅ | ✅ | `*`, `+`, `-` supported |
| Ordered Lists | ✅ `.` `)` | ⚠️ `.` only | RDoc doesn't support `)` delimiter |
| Nested Lists | ✅ | ✅ | 4-space indentation |
| Tables | ✅ | ✅ | Full alignment support |
| Thematic Breaks | ✅ | ✅ | `---`, `***`, `___` |
| HTML Blocks | ✅ 7 types | ⚠️ | See below |

#### HTML Blocks

GFM defines 7 types of HTML blocks:

| Type | Description | GFM | RDoc |
|------|-------------|:---:|:----:|
| 1 | `<script>`, `<pre>` | ✅ | ✅ |
| 1 | `<style>` | ✅ | ❌ |
| 2 | HTML comments `<!-- -->` | ✅ | ✅ |
| 3 | Processing instructions `<? ?>` | ✅ | ❌ |
| 4 | Declarations `<!DOCTYPE>` | ✅ | ❌ |
| 5 | CDATA `<![CDATA[ ]]>` | ✅ | ❌ |
| 6 | Block-level tags | ✅ | ⚠️ |
| 7 | Any complete open/close tag | ✅ | ❌ |

RDoc uses a whitelist of block-level tags defined in
[lib/rdoc/markdown.kpeg](https://github.com/ruby/rdoc/blob/master/lib/rdoc/markdown.kpeg)
(see `HtmlBlockInTags`). HTML5 semantic elements like `<article>`, `<section>`,
`<nav>`, `<header>`, `<footer>` are not supported.

### Inline Elements

| Feature | GFM | RDoc | Notes |
|---------|:---:|:----:|-------|
| Emphasis `*text*` `_text_` | ✅ | ✅ | Full match |
| Strong `**text**` `__text__` | ✅ | ✅ | Full match |
| Combined `***text***` | ✅ | ✅ | Full match |
| Code spans | ✅ | ✅ | Multiple backticks supported |
| Inline links | ✅ | ✅ | Full match |
| Reference links | ✅ | ✅ | Full match |
| Link titles | ✅ | ⚠️ | Parsed but not rendered |
| Images | ✅ | ✅ | Full match |
| Autolinks `<url>` | ✅ | ✅ | Full match |
| Hard line breaks | ✅ | ✅ | 2+ trailing spaces |
| Backslash escapes | ✅ | ✅ | Full match |
| HTML entities | ✅ | ✅ | Named, decimal, hex |
| Inline HTML | ✅ | ✅ | Full match |

### GFM Extensions

| Feature | GFM | RDoc | Notes |
|---------|:---:|:----:|-------|
| Strikethrough `~~text~~` | ✅ | ✅ | Full match |
| Task Lists `[ ]` `[x]` | ✅ | ❌ | Not supported |
| Extended Autolinks | ✅ | ❌ | See below |
| Disallowed Raw HTML | ✅ | ❌ | No security filtering |

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

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

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

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

### RDoc-Specific Features (not in GFM)

- [Definition Lists](#definition-lists)
- [Footnotes](#footnotes)
- [Cross-references](#cross-references)
- [Anchor Links](#anchor-links)
- [Directives](#directives)
Loading