inline verbatim
-text. That should be enough of a taste of inline markup in paragraphs.
-The Riker Ipsum filler follows:
-
-Shields up! Rrrrred alert! Well, I'll say this for him - he's sure of himself.
-and attack the Romulans. Worf, It's better than music. It's jazz. This should
-be interesting. When has justice ever been as simple as a rule book? Flair is
-what marks the difference between artistry and mere competence.
-
-Sorry, Data. I think you've let your personal feelings cloud your judgement. We
-finished our first sensor sweep of the neutral zone. Yes, absolutely, I do
-indeed concur, wholeheartedly! Mr. Worf, you do remember how to fire phasers? A
-lot of things can change in twelve years, Admiral. Your shields were failing,
-sir.
-
-== Verbatim sections
-
-A verbatim section typically contains source code or example output. This is
-how verbatim blocks of code looks:
-
- def local responder
- responder.ping do |value|
- return value
- end
- end
-
- def ping uri
- @uri = uri
- @remote = DRb::DRbObject.new_with_uri @uri
-
- @remote.ping do |value|
- return value
- end
- end
-
-This is a paragraph following the verbatim block so you can see how leading and trailing paragraphs interact with it.
-
-== Unordered lists
-
-Here is an unordered list. As you can see it uses non-numeral markers for each list item:
-
-* This is the top-most item in the list.
-* This is a second item in the list.
-
- Unlike the first item, this item has more than one paragraph so you can see
- how they interact.
-* This is a third item in the list. Like the item before it, this item has a
- second paragraph.
-
- Here is the second paragraph in the list item.
-* A final list item.
-
-== Ordered lists
-
-Here is an ordered list. As you can see it uses numeral markers for each list
-item:
-
-1. This is the first item in the list.
-1. This is the second item in the list.
-
- Unlike the first item, this item has more than one paragraph so you can see
- how they interact.
-1. This is the third item in the list. Like the item before it, this item has
- a second paragraph.
-
- Here is the second paragraph in the third list item.
-1. The fourth and final list item.
-
-== Definition lists
-
-=== "Note" list
-
-The "note" syntax can be used to create a definition list:
-
- note::
- description
-
-Here is such a definition list:
-
-cat::
- A cat is a small mammal that is commonly kept as a pet.
-
-dog::
- A dog is a mammal that is also kept as a pet. A dog may range in size from
- smaller than a cat to larger than a human.
-
- Typically dogs are easier to train to respond to commands than cats.
-
-rabbit::
- Rabbits are also mammals, but are infrequently kept as pets. Most rabbits
- are wild.
-
-=== "Label" list
-
-The "label" syntax can be used to create a definition list:
-
- [label]
- description
-
-Here is such a definition list:
-
-[cat]
- A cat is a small mammal that is commonly kept as a pet.
-
-[dog]
- A dog is a mammal that is also kept as a pet. A dog may range in size from
- smaller than a cat to larger than a human.
-
- Typically dogs are easier to train to respond to commands than cats.
-
-[rabbit]
- Rabbits are also mammals, but are infrequently kept as pets. Most rabbits
- are wild.
-
-== Rule
-
-A rule is a horizontal divider between two paragraphs. Following this
-paragraph is a rule.
-
----
-
-In historic versions of RDoc you could control the height of the rule in HTML
-output. This is no longer true as HTML 5 does not support this.
-
diff --git a/README.md b/README.md
index 9eecfc0d0d..71b894cd9e 100644
--- a/README.md
+++ b/README.md
@@ -60,7 +60,7 @@ You can specify the target files for document generation with `.document` file i
## Writing Documentation
-To write documentation for RDoc place a comment above the class, module, method, constant, or attribute you want documented:
+To write documentation for RDoc, place a comment above the class, module, method, constant, or attribute you want documented:
```rb
##
@@ -80,13 +80,79 @@ class Shape
end
```
-The default comment markup format is the RDoc::Markup format. TomDoc, Markdown and RD format comments are also supported. You can set the default comment format for your entire project by creating a `.rdoc_options` file. See RDoc::Options@Saved+Options for instructions on creating one. You can also set the comment format for a single file through the `:markup:` directive, but this is only recommended if you wish to switch markup formats. See RDoc::Markup@Other+directives.
+### Markup Formats
-Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing. See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic. See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
+RDoc supports multiple markup formats:
+
+| Format | File Extensions | Default For |
+|--------|-----------------|-------------|
+| [RDoc](doc/markup_reference/rdoc.rdoc) | `.rdoc` | `.rb`, `.c` files |
+| [Markdown](doc/markup_reference/markdown.md) | `.md` | None |
+| RD | `.rd` | None |
+| TomDoc | N/A | None |
+
+**RDoc markup** is currently the default format for Ruby and C files. However, we plan to retire it in favor of Markdown in the future.
+
+**Markdown** support is actively being improved. Once it reaches feature parity with RDoc markup, it will become the default format.
+
+For standalone documentation files, we recommend writing `.md` files instead of `.rdoc` files.
+
+**RD** and **TomDoc** are legacy formats. We highly discourage their use in new projects.
+
+### Specifying Markup Format
+
+**Per-file:** Add a `:markup:` directive at the top of a Ruby file:
+
+```ruby
+# :markup: markdown
+
+# This class uses **Markdown** for documentation.
+class MyClass
+end
+```
+
+**Per-project:** Create a `.rdoc_options` file in your project root:
+
+```yaml
+markup: markdown
+```
+
+**Command line:**
+
+```bash
+rdoc --markup markdown
+```
+
+### Feature Differences
+
+| Feature | RDoc Markup | Markdown |
+|---------|-------------|----------|
+| Headings | `= Heading` | `# Heading` |
+| Bold | `*word*` | `**word**` |
+| Italic | `_word_` | `*word*` |
+| Monospace | `+word+` | `` `word` `` |
+| Links | `{text}[url]` | `[text](url)` |
+| Code blocks | Indent 2 spaces | Fenced with ``` |
+| Cross-references | Automatic | Automatic |
+| Directives (`:nodoc:`, etc.) | Supported | Supported |
+| Tables | Not supported | Supported |
+| Strikethrough | Not supported | Supported |
+| Footnotes | Not supported | Supported |
+
+For complete syntax documentation, see:
+
+- [RDoc Markup Reference](doc/markup_reference/rdoc.rdoc)
+- [Markdown Reference](doc/markup_reference/markdown.md)
+
+### Directives
+
+Comments can contain directives that tell RDoc information that it cannot otherwise discover through parsing. See RDoc::Markup@Directives to control what is or is not documented, to define method arguments or to break up methods in a class by topic. See RDoc::Parser::Ruby for directives used to teach RDoc about metaprogrammed methods.
See RDoc::Parser::C for documenting C extensions with RDoc.
-To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report. `rdoc -C1 lib` includes parameter names in the documentation coverage report.
+### Documentation Coverage
+
+To determine how well your project is documented run `rdoc -C lib` to get a documentation coverage report. `rdoc -C1 lib` includes parameter names in the documentation coverage report.
## Theme Options
diff --git a/bin/console b/bin/console
index 2090c32bd8..fd6999e48d 100755
--- a/bin/console
+++ b/bin/console
@@ -4,7 +4,7 @@ require 'bundler/setup'
require 'rdoc'
# This is the easy way to prepare various kinds of RDoc objects.
-require_relative '../doc/rdoc/markup_reference'
+require_relative '../doc/rdoc/example'
require 'irb'
IRB.start(__FILE__)
diff --git a/doc/markup_reference/markdown.md b/doc/markup_reference/markdown.md
new file mode 100644
index 0000000000..49f87ada0f
--- /dev/null
+++ b/doc/markup_reference/markdown.md
@@ -0,0 +1,558 @@
+# 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](#paragraphs): ordinary text blocks.
+- [Headings](#headings): section titles.
+- [Code Blocks](#code-blocks): verbatim text with syntax highlighting.
+- [Blockquotes](#blockquotes): quoted passages.
+- [Lists](#lists): bullet, numbered, and definition lists.
+- [Tables](#tables): tabular data.
+- [Horizontal Rules](#horizontal-rules): visual separators.
+
+### Paragraphs
+
+A paragraph is one or more consecutive lines of text,
+separated from other blocks by blank lines.
+
+Example:
+
+```markdown
+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:
+
+```markdown
+# Heading Level 1
+## Heading Level 2
+### Heading Level 3
+#### Heading Level 4
+##### Heading Level 5
+###### Heading Level 6
+```
+
+Optional closing `#` characters are allowed:
+
+```markdown
+## Heading ##
+```
+
+#### Setext-Style Headings
+
+Underline text with `=` for level 1 or `-` for level 2:
+
+```markdown
+Heading Level 1
+===============
+
+Heading Level 2
+---------------
+```
+
+### Code Blocks
+
+#### Indented Code Blocks
+
+Indent code by 4 spaces or 1 tab:
+
+```markdown
+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 `>`:
+
+```markdown
+> This is a blockquote.
+> It can span multiple lines.
+>
+> Multiple paragraphs are supported.
+```
+
+Blockquotes can contain other elements:
+
+```markdown
+> ## Heading inside blockquote
+>
+> - List item 1
+> - List item 2
+>
+> Code inside blockquote:
+>
+> def example
+> :ok
+> end
+```
+
+Nested blockquotes:
+
+```markdown
+> Outer quote
+>
+> > Nested quote
+```
+
+### Lists
+
+#### Bullet Lists
+
+Use `*`, `+`, or `-` followed by a space:
+
+```markdown
+* Item 1
+* Item 2
+* Item 3
+```
+
+Or:
+
+```markdown
+- Item 1
+- Item 2
+- Item 3
+```
+
+#### Numbered Lists
+
+Use digits followed by `.` and a space:
+
+```markdown
+1. First item
+2. Second item
+3. Third item
+```
+
+The actual numbers don't matter; they're renumbered in output:
+
+```markdown
+1. First
+1. Second
+1. Third
+```
+
+#### Nested Lists
+
+Indent with 4 spaces to nest:
+
+```markdown
+* 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:
+
+```markdown
+term
+: Definition of the term.
+
+cat
+: A small furry mammal.
+
+ant
+: A little insect.
+```
+
+Multiple definitions for one term:
+
+```markdown
+apple
+: A fruit
+: A technology company
+```
+
+### Tables
+
+Create tables with pipes and dashes:
+
+```markdown
+| 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:
+
+```markdown
+| 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:
+
+```markdown
+| Feature | Syntax |
+|-------------|-----------------|
+| **Bold** | `**text**` |
+| *Italic* | `*text*` |
+| `Code` | `` `text` `` |
+```
+
+### Horizontal Rules
+
+Use three or more `-`, `*`, or `_` on a line by themselves:
+
+```markdown
+---
+
+* * *
+
+___
+```
+
+## Text Markup
+
+Inline text can be formatted with various markup:
+
+- [Italic](#italic): emphasized text.
+- [Bold](#bold): strong emphasis.
+- [Bold and Italic](#bold-and-italic): combined emphasis.
+- [Strikethrough](#strikethrough): deleted text.
+- [Inline Code](#inline-code): monospace text.
+
+### Italic
+
+Use single asterisks or underscores:
+
+```markdown
+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:
+
+```markdown
+foo_bar_baz remains plain text
+```
+
+### Bold
+
+Use double asterisks or underscores:
+
+```markdown
+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:
+
+```markdown
+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:
+
+```markdown
+This is ~~strikethrough~~ text.
+```
+
+> This is ~~strikethrough~~ text.
+
+### Inline Code
+
+Use backticks:
+
+```markdown
+Use the `puts` method.
+```
+
+> Use the `puts` method.
+
+For code containing backticks, use multiple backticks:
+
+```markdown
+Use `` `backticks` `` in code.
+```
+
+> Use `` `backticks` `` in code.
+
+## Links
+
+### Inline Links
+
+```markdown
+[Link text](https://example.com)
+```
+
+> [Link text](https://example.com)
+
+With optional title (title is parsed but not used in RDoc output):
+
+```markdown
+[Link text](https://example.com "Title")
+```
+
+### Reference Links
+
+Define a reference, then use it:
+
+```markdown
+[Link text][ref]
+
+[ref]: https://example.com
+```
+
+Implicit reference (link text matches reference):
+
+```markdown
+[Example][]
+
+[Example]: https://example.com
+```
+
+### Autolinks
+
+URLs and emails in angle brackets become links:
+
+```markdown
+This is HTML content.
+`, ``, +`