From 0bdfb37b908fd22602a32840ff9e895dae69d490 Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Wed, 31 Dec 2025 21:49:48 +0000
Subject: [PATCH 1/2] Rebuild RDoc markup documentation

1. README now has a better section about supported markup formats
2. RDoc markup related reference are now consolidated under `doc/markup_reference/rdoc.rdoc`
3. Markdown markup now has a more comprehensive reference in `doc/markup_reference/markdown.md`
---
 AGENTS.md                        |    8 +-
 ExampleMarkdown.md               |   50 --
 ExampleRDoc.rdoc                 |  222 -----
 README.md                        |   74 +-
 bin/console                      |    2 +-
 doc/markup_reference/markdown.md |  558 +++++++++++++
 doc/markup_reference/rdoc.rdoc   | 1136 ++++++++++++++++++++++++++
 doc/rdoc/example.rb              |  102 +++
 doc/rdoc/markup_reference.rb     | 1308 ------------------------------
 rdoc.gemspec                     |    4 +-
 10 files changed, 1873 insertions(+), 1591 deletions(-)
 delete mode 100644 ExampleMarkdown.md
 delete mode 100644 ExampleRDoc.rdoc
 create mode 100644 doc/markup_reference/markdown.md
 create mode 100644 doc/markup_reference/rdoc.rdoc
 create mode 100644 doc/rdoc/example.rb
 delete mode 100644 doc/rdoc/markup_reference.rb

diff --git a/AGENTS.md b/AGENTS.md
index ddfdc9f664..26520d72b6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -220,10 +220,10 @@ exe/
 
 ### Documentation
 
-- `README.md` - Basic usage guide
-- `ExampleRDoc.rdoc` - RDoc markup examples
-- `doc/rdoc/markup_reference.rb` - RDoc markup references
-- `ExampleMarkdown.md` - Markdown examples
+- `README.md` - Basic usage guide and markup format reference
+- `markup_reference/rdoc.rdoc` - Comprehensive RDoc markup syntax reference
+- `markup_reference/markdown.md` - Markdown syntax reference
+- `doc/rdoc/example.rb` - Ruby code examples for cross-references and directives
 
 ## Architecture Notes
 
diff --git a/ExampleMarkdown.md b/ExampleMarkdown.md
deleted file mode 100644
index 8622fcab77..0000000000
--- a/ExampleMarkdown.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# Example Markdown
-
-This document contains example output to show RDoc styling.  This file was
-created from a Markdown file.
-
-For the following styles, see ExampleRDoc.rdoc for style examples:
-
-* Headings
-* Paragraphs
-* Code blocks (verbatim sections)
-* Definition lists
-* Ordered lists
-* Unordered lists
-
-These items all use the same styles as RDoc format files.
-
-## 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](#footnotes)
-* [Link to Blockquotes](#blockquotes)
-* [Link to Anchor Links](#anchor-links)
-
-## Footnotes
-
-Footnotes are rendered at the bottom of the documentation section[^1].  For
-pages this will be at the bottom of the page.  For method documentation this
-will be at the end of the current method.
-
-[^1]: Here is the footnote content.  As you can see it is at the bottom of the
-page.
-
-## Blockquotes
-
-Here is how a blockquote looks.
-
-> We finished our first sensor sweep of the neutral zone. Now, how the hell do
-> we defeat an enemy that knows us better than we know ourselves? and attack
-> the Romulans.
->
-> > Sorry, Data. I guess it's better to be lucky than good. The unexpected is
-> > our normal routine. Could someone survive inside a transporter buffer for
-> > 75 years?
-
-This text is from [Riker Ipsum](http://rikeripsum.com)
diff --git a/ExampleRDoc.rdoc b/ExampleRDoc.rdoc
deleted file mode 100644
index 750fdc4795..0000000000
--- a/ExampleRDoc.rdoc
+++ /dev/null
@@ -1,222 +0,0 @@
-= Example \RDoc
-
-This document contains example output to show RDoc styling.  This file was
-created from a RDoc Markup file.
-
-== Anchor Links
-
-RDoc generates GitHub-style anchors for headings.  The anchor is the heading
-text converted to lowercase with spaces replaced by hyphens and special
-characters removed.
-
-You can link to headings using Markdown-style syntax:
-
-- {Link to Headings}[#headings]
-- {Link to Paragraphs}[#paragraphs]
-- {Link to Verbatim sections}[#verbatim-sections]
-
-== Headings
-
-You should not use headings beyond level 3, it is a sign of poor organization
-of your code or documentation.  It also becomes difficult for the user to
-figure out what you are attempting to explain to them as they have to track
-the multiple layers of nesting.
-
-= Heading level 1
-
-Above is a level one heading.
-
-These paragraphs are filler that exist so you can see how the heading
-interacts with paragraphs before and after the heading.  As you can see each
-different heading has a different amount of margin above and below.
-
-This should be sufficient to give you a proper picture of how it will appear in
-your documentation.
-
-== Heading level 2
-
-Above is a level two heading.
-
-These paragraphs are filler that exist so you can see how the heading
-interacts with paragraphs before and after the heading.  As you can see each
-different heading has a different amount of margin above and below.
-
-This should be sufficient to give you a proper picture of how it will appear in
-your documentation.
-
-=== Heading level 3
-
-Above is a level three heading.
-
-These paragraphs are filler that exist so you can see how the heading
-interacts with paragraphs before and after the heading.  As you can see each
-different heading has a different amount of margin above and below.
-
-This should be sufficient to give you a proper picture of how it will appear in
-your documentation.
-
-==== Heading level 4
-
-Above is a level four heading.
-
-These paragraphs are filler that exist so you can see how the heading
-interacts with paragraphs before and after the heading.  As you can see each
-different heading has a different amount of margin above and below.
-
-This should be sufficient to give you a proper picture of how it will appear in
-your documentation.
-
-===== Heading level 5
-
-Above is a level five heading.
-
-These paragraphs are filler that exist so you can see how the heading
-interacts with paragraphs before and after the heading.  As you can see each
-different heading has a different amount of margin above and below.
-
-This should be sufficient to give you a proper picture of how it will appear in
-your documentation.
-
-====== Heading level 6
-
-Above is a level six heading.
-
-These paragraphs are filler that exist so you can see how the heading
-interacts with paragraphs before and after the heading.  As you can see each
-different heading has a different amount of margin above and below.
-
-This should be sufficient to give you a proper picture of how it will appear in
-your documentation.
-
-== Paragraphs
-
-This is how a paragraph looks.  Since it is difficult to generate good content
-for paragraphs I have chosen to use {Riker Ipsum}[http://rikeripsum.com] for
-nonsense filler content.  In the previous sentence you can see how a link is
-formatted.
-
-Here is an example of *bold* and _emphasis_ styling.  Try not to combine the
-two or use them too often.  Here is an example of <code>inline verbatim
-text</code>.  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
+<https://example.com>
+<user@example.com>
+```
+
+> <https://example.com>
+> <user@example.com>
+
+### Cross-References
+
+Link to RDoc-documented classes, modules, and methods:
+
+```markdown
+[RDoc module](rdoc-ref:RDoc)
+[Options class](rdoc-ref:RDoc::Options)
+[document method](rdoc-ref:RDoc::RDoc#document)
+```
+
+See [rdoc.rdoc](rdoc.rdoc) for complete cross-reference documentation.
+
+## Images
+
+Basic image syntax:
+
+```markdown
+![Alt text](path/to/image.png)
+```
+
+Image as a link:
+
+```markdown
+[![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](#footnotes)
+* [Link to Blockquotes](#blockquotes)
+* [Link to Anchor Links](#anchor-links)
+
+## Footnotes
+
+### Reference Footnotes
+
+Add a footnote reference in text, then define it:
+
+```markdown
+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:
+
+```markdown
+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:
+
+```markdown
+<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:
+
+```markdown
+This has <b>bold</b> and <em>emphasized</em> HTML.
+```
+
+## Special Characters
+
+### Escaping
+
+Use backslash to escape special characters:
+
+```markdown
+\*not italic\*
+\`not code\`
+\[not a link\]
+\# not a heading
+```
+
+Escapable characters: `` ` \ : | * _ { } [ ] ( ) # + . ! > < - ``
+
+### HTML Entities
+
+Named, decimal, and hexadecimal entities are supported:
+
+```markdown
+&copy; &mdash; &pi;
+&#65; &#x41;
+```
+
+## Line Breaks
+
+End a line with two or more spaces for a hard line break:
+
+```markdown
+Line one
+Line two
+```
+
+## Directives
+
+RDoc directives work in Markdown files within Ruby comments.
+Use the `:markup: markdown` directive to specify Markdown format.
+
+```ruby
+# :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](rdoc.rdoc) for complete directive documentation.
+
+## Comparison with RDoc Markup
+
+| Feature | RDoc Markup | Markdown |
+|---------|-------------|----------|
+| Headings | `= Heading` | `# Heading` |
+| Bold | `*word*` | `**word**` |
+| Italic | `_word_` | `*word*` |
+| Monospace | `+word+` | `` `word` `` |
+| Links | `{text}[url]` | `[text](url)` |
+| Code blocks | Indent beyond margin | Indent 4 spaces or fence |
+| Block quotes | `>>>` | `>` |
+| Tables | Not supported | Supported |
+| Strikethrough | Not supported | `~~text~~` |
+| Footnotes | Not supported | `[^1]` |
+
+## 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.
diff --git a/doc/markup_reference/rdoc.rdoc b/doc/markup_reference/rdoc.rdoc
new file mode 100644
index 0000000000..8a4025af62
--- /dev/null
+++ b/doc/markup_reference/rdoc.rdoc
@@ -0,0 +1,1136 @@
+= RDoc Markup Reference
+
+This document is the comprehensive reference for RDoc's +rdoc+ markup format.
+It covers all markup syntax, directives, 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.
+
+== Anchor Links
+
+RDoc generates GitHub-style anchors for headings.  The anchor is the heading
+text converted to lowercase with spaces replaced by hyphens and special
+characters removed.
+
+You can link to headings using Markdown-style syntax:
+
+- {Link to Headings}[#headings]
+- {Link to Paragraphs}[#paragraphs]
+- {Link to Verbatim Text Blocks}[#verbatim-text-blocks]
+
+== About the Examples
+
+- Examples in this reference show RDoc markup syntax.
+- An example that shows rendered HTML output displays that output in a blockquote:
+
+  >>>
+    Some rendered output
+
+== Markup Sources
+
+The sources of markup documentation vary according to the file type:
+
+- <tt>.rb</tt> (Ruby code file):
+
+  - Markup may be found in Ruby comments:
+    A comment that immediately precedes the definition
+    of a class, module, method, alias, constant, or attribute
+    becomes the documentation for that defined object.
+  - A markup directive may be found in:
+
+    - A trailing comment (on the same line as code);
+      see <tt>:nodoc:</tt>, <tt>:doc:</tt>, and <tt>:notnew:</tt>.
+    - A single-line comment;
+      see other Directives below.
+
+  - Documentation may be derived from the Ruby code itself;
+    see Derived Documentation below.
+
+- <tt>.c</tt> (C code file): markup is parsed from C comments.
+  A comment that immediately precedes
+  a function that implements a Ruby method,
+  or otherwise immediately precedes the definition of a Ruby object,
+  becomes the documentation for that object.
+
+- <tt>.rdoc</tt> (markup file):
+  markup is parsed from the entire file.
+  The text is not associated with any code object,
+  but may (depending on how the documentation is built)
+  become a separate page.
+
+Note that all of the above applies to RDoc +markup+-formatted documentation:
+
+- A C- or Ruby-coded file may contain <tt>markdown</tt>-formatted documentation,
+  though that format must be declared (because the default is +markup+).
+- A markdown (<tt>.md</tt>) file contains only <tt>markdown</tt>-formatted documentation.
+
+== Blocks
+
+It's convenient to think of an RDoc document as a sequence of _blocks_
+of various types:
+
+- {Paragraph}[rdoc-ref:rdoc@Paragraphs]: an ordinary paragraph.
+- {Verbatim text block}[rdoc-ref:rdoc@Verbatim+Text+Blocks]: a block of text to be rendered literally.
+- {Code block}[rdoc-ref:rdoc@Code+Blocks]: a verbatim text block containing Ruby code,
+  to be rendered with code highlighting.
+- {Block quote}[rdoc-ref:rdoc@Block+Quotes]: a longish quoted passage, to be rendered with indentation
+  instead of quote marks.
+- {List}[rdoc-ref:rdoc@Lists]: items for a bullet list, numbered list, lettered list, or labeled list.
+- {Heading}[rdoc-ref:rdoc@Headings]: a heading.
+- {Horizontal rule}[rdoc-ref:rdoc@Horizontal+Rules]: a line across the rendered page.
+- {Directive}[rdoc-ref:rdoc@Directives]: various special directions for the rendering.
+- {Text Markup}[rdoc-ref:rdoc@Text+Markup]: text to be rendered in a special way.
+
+About the blocks:
+
+- Except for a paragraph, a block is distinguished by its indentation,
+  or by unusual initial or embedded characters.
+- Any block may appear independently
+  (that is, not nested in another block);
+  some blocks may be nested, as detailed below.
+- In a multi-line block,
+  RDoc looks for the block's natural left margin,
+  which becomes the <em>base margin</em> for the block
+  and is the initial <em>current margin</em> for the block.
+
+=== Paragraphs
+
+A paragraph consists of one or more non-empty lines of ordinary text,
+each beginning at the current margin.
+
+Note: Here, <em>ordinary text</em> means text that is <em>not identified</em>
+by indentation, or by unusual initial or embedded characters.
+See below.
+
+Paragraphs are separated by one or more empty lines.
+
+Example input:
+
+  RDoc produces HTML and command-line documentation for Ruby projects.
+  RDoc includes the rdoc and ri tools for generating and displaying
+  documentation from the command-line.
+
+  You'll love it.
+
+Rendered HTML:
+>>>
+  RDoc produces HTML and command-line documentation for Ruby projects.
+  RDoc includes the rdoc and ri tools for generating and displaying
+  documentation from the command-line.
+
+  You'll love it.
+
+A paragraph may contain nested blocks, including:
+
+- {Verbatim text blocks}[rdoc-ref:rdoc@Verbatim+Text+Blocks].
+- {Code blocks}[rdoc-ref:rdoc@Code+Blocks].
+- {Block quotes}[rdoc-ref:rdoc@Block+Quotes].
+- {Lists}[rdoc-ref:rdoc@Lists].
+- {Headings}[rdoc-ref:rdoc@Headings].
+- {Horizontal rules}[rdoc-ref:rdoc@Horizontal+Rules].
+- {Text Markup}[rdoc-ref:rdoc@Text+Markup].
+
+=== Verbatim Text Blocks
+
+Text indented farther than the current margin becomes a <em>verbatim text block</em>
+(or a code block, described next).
+In the rendered HTML, such text:
+
+- Is indented.
+- Has a contrasting background color.
+
+The verbatim text block ends at the first line beginning at the current margin.
+
+Example input:
+
+  This is not verbatim text.
+
+    This is verbatim text.
+      Whitespace is honored.     # See?
+        Whitespace is honored.     # See?
+
+    This is still the same verbatim text block.
+
+  This is not verbatim text.
+
+Rendered HTML:
+>>>
+  This is not verbatim text.
+
+    This is verbatim text.
+      Whitespace is honored.     # See?
+        Whitespace is honored.     # See?
+
+    This is still the same verbatim text block.
+
+  This is not verbatim text.
+
+A verbatim text block may not contain nested blocks of any kind
+-- it's verbatim.
+
+=== Code Blocks
+
+A special case of verbatim text is the <em>code block</em>,
+which is merely verbatim text that RDoc recognizes as Ruby code:
+
+In the rendered HTML, the code block:
+
+- Is indented.
+- Has a contrasting background color.
+- Has syntax highlighting.
+
+Example input:
+
+  Consider this method:
+
+    def foo(name = '', value = 0)
+      @name = name      # Whitespace is still honored.
+      @value = value
+    end
+
+Rendered HTML:
+>>>
+  Consider this method:
+
+    def foo(name = '', value = 0)
+      @name = name      # Whitespace is still honored.
+      @value = value
+    end
+
+Pro tip: If your indented Ruby code does not get highlighted,
+it may contain a syntax error.
+
+A code block may not contain nested blocks of any kind
+-- it's verbatim.
+
+=== Block Quotes
+
+You can use the characters <tt>>>></tt> (unindented),
+followed by indented text, to treat the text
+as a block quote[https://en.wikipedia.org/wiki/Block_quotation]:
+
+Example input:
+
+  Here's a block quote:
+  >>>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
+    commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
+    Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.
+
+    Aenean congue ligula eu ligula molestie, eu pellentesque purus
+    faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
+    diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
+    purus magna ut tortor.
+
+Rendered HTML:
+
+>>>
+  Here's a block quote:
+  >>>
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
+    commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
+    Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.
+
+    Aenean congue ligula eu ligula molestie, eu pellentesque purus
+    faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
+    diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
+    purus magna ut tortor.
+
+Note that, unlike verbatim text, single newlines are not honored,
+but that a double newline begins a new paragraph in the block quote.
+
+A block quote may contain nested blocks, including:
+
+- Other {block quotes}[rdoc-ref:rdoc@Block+Quotes].
+- {Paragraphs}[rdoc-ref:rdoc@Paragraphs].
+- {Verbatim text blocks}[rdoc-ref:rdoc@Verbatim+Text+Blocks].
+- {Code blocks}[rdoc-ref:rdoc@Code+Blocks].
+- {Lists}[rdoc-ref:rdoc@Lists].
+- {Headings}[rdoc-ref:rdoc@Headings].
+- {Horizontal rules}[rdoc-ref:rdoc@Horizontal+Rules].
+- {Text Markup}[rdoc-ref:rdoc@Text+Markup].
+
+=== Lists
+
+Each type of list item is marked by a special beginning:
+
+- Bullet list item: Begins with a hyphen or asterisk.
+- Numbered list item: Begins with digits and a period.
+- Lettered list item: Begins with an alphabetic character and a period.
+- Labeled list item: Begins with one of:
+  - Square-bracketed text.
+  - A word followed by two colons.
+
+A list begins with a list item and continues, even across blank lines,
+as long as list items of the same type are found at the same indentation level.
+
+A new list resets the current margin inward.
+Additional lines of text aligned at that margin
+are part of the continuing list item.
+
+A list item may be continued on additional lines that are aligned
+with the first line. See examples below.
+
+A list item may contain nested blocks, including:
+
+- Other {lists}[rdoc-ref:rdoc@Lists] of any type.
+- {Paragraphs}[rdoc-ref:rdoc@Paragraphs].
+- {Verbatim text blocks}[rdoc-ref:rdoc@Verbatim+Text+Blocks].
+- {Code blocks}[rdoc-ref:rdoc@Code+Blocks].
+- {Block quotes}[rdoc-ref:rdoc@Block+Quotes].
+- {Headings}[rdoc-ref:rdoc@Headings].
+- {Horizontal rules}[rdoc-ref:rdoc@Horizontal+Rules].
+- {Text Markup}[rdoc-ref:rdoc@Text+Markup].
+
+==== Bullet Lists
+
+A bullet list item begins with a hyphen or asterisk.
+
+Example input:
+
+  - An item.
+  - Another.
+  - An item spanning
+    multiple lines.
+
+  * Yet another.
+  - Last one.
+
+Rendered HTML:
+>>>
+  - An item.
+  - Another.
+  - An item spanning
+    multiple lines.
+
+  * Yet another.
+  - Last one.
+
+==== Numbered Lists
+
+A numbered list item begins with digits and a period.
+
+The items are automatically re-numbered.
+
+Example input:
+
+  100. An item.
+  10. Another.
+  1. An item spanning
+     multiple lines.
+
+  1. Yet another.
+  1000. Last one.
+
+Rendered HTML:
+>>>
+  100. An item.
+  10. Another.
+  1. An item spanning
+     multiple lines.
+
+  1. Yet another.
+  1000. Last one.
+
+==== Lettered Lists
+
+A lettered list item begins with letters and a period.
+
+The items are automatically "re-lettered."
+
+Example input:
+
+  z. An item.
+  y. Another.
+  x. An item spanning
+     multiple lines.
+
+  x. Yet another.
+  a. Last one.
+
+Rendered HTML:
+>>>
+  z. An item.
+  y. Another.
+  x. An item spanning
+     multiple lines.
+
+  x. Yet another.
+  a. Last one.
+
+==== Labeled Lists
+
+A labeled list item begins with one of:
+
+- Square-bracketed text: the label and text are on two lines.
+- A word followed by two colons: the label and text are on the same line.
+
+Example input:
+
+  [foo] An item.
+  bat:: Another.
+  [bag] An item spanning
+        multiple lines.
+
+  [bar baz] Yet another.
+  bam:: Last one.
+
+Rendered HTML:
+>>>
+  [foo] An item.
+  bat:: Another.
+  [bag] An item spanning
+        multiple lines.
+
+  [bar baz] Yet another.
+  bam:: Last one.
+
+=== Headings
+
+A heading begins with up to six equal-signs, followed by heading text.
+Whitespace between those and the heading text is optional.
+
+You should not use headings beyond level 3, as it becomes difficult
+for the reader to track the multiple layers of nesting.
+
+Examples:
+
+  = Section 1
+  == Section 1.1
+  === Section 1.1.1
+  === Section 1.1.2
+  == Section 1.2
+  = Section 2
+  ============Still a Heading (Level 6)
+  \== Not a Heading
+
+A heading may contain only one type of nested block:
+
+- {Text Markup}[rdoc-ref:rdoc@Text+Markup].
+
+==== Heading Examples
+
+= Heading level 1
+
+Above is a level one heading.
+
+== Heading level 2
+
+Above is a level two heading.
+
+=== Heading level 3
+
+Above is a level three heading.
+
+==== Heading level 4
+
+Above is a level four heading.
+
+===== Heading level 5
+
+Above is a level five heading.
+
+====== Heading level 6
+
+Above is a level six heading.
+
+=== Horizontal Rules
+
+A horizontal rule consists of a line with three or more hyphens
+and nothing more.
+
+Example input:
+
+  ---
+  --- Not a horizontal rule.
+
+  -- Also not a horizontal rule.
+  ---
+
+Rendered HTML:
+>>>
+  ---
+  --- Not a horizontal rule.
+
+  -- Also not a horizontal rule.
+  ---
+
+== Directives
+
+=== Directives for Allowing or Suppressing Documentation
+
+==== <tt>:stopdoc:</tt>
+
+- Appears on a line by itself.
+- Specifies that RDoc should ignore markup
+  until next <tt>:startdoc:</tt> directive or end-of-file.
+
+==== <tt>:startdoc:</tt>
+
+- Appears on a line by itself.
+- Specifies that RDoc should resume parsing markup.
+
+==== <tt>:enddoc:</tt>
+
+- Appears on a line by itself.
+- Specifies that RDoc should ignore markup to end-of-file
+  regardless of other directives.
+
+==== <tt>:nodoc:</tt>
+
+- Appended to a line of code
+  that defines a class, module, method, alias, constant, or attribute;
+  takes optional argument +all+ (<tt>:nodoc: all</tt>).
+- Specifies that the defined object should not be documented.
+
+For a method definition in C code, the directive must be in the comment line
+immediately preceding the definition:
+
+  /* :nodoc: */
+  static VALUE
+  some_method(VALUE self)
+  {
+    return self;
+  }
+
+Note that this directive has <em>no effect at all</em>
+when placed at the method declaration:
+
+  /* :nodoc: */
+  rb_define_method(cMyClass, "do_something", something_func, 0);
+
+The above comment is just a comment and has nothing to do with RDoc.
+Therefore, +do_something+ method will be reported as "undocumented"
+unless that method or function is documented elsewhere.
+
+For a constant definition in C code, this directive <em>cannot work</em>
+because there is no "implementation" place for a constant.
+
+With argument +all+ (<tt>:nodoc: all</tt>),
+specifies that the class or module should not be documented.
+By default, however, a nested class or module _will_ be documented.
+
+==== <tt>:doc:</tt>
+
+- Appended to a line of code
+  that defines a class, module, method, alias, constant, or attribute.
+- Specifies the defined object should be documented, even if it otherwise
+  would not be documented.
+
+==== <tt>:notnew:</tt>
+
+- Appended to a line of code
+  that defines instance method +initialize+.
+- Specifies that singleton method +new+ should not be documented.
+  By default, Ruby fakes a corresponding singleton method +new+,
+  which RDoc includes in the documentation.
+  Note that instance method +initialize+ is private, and so by default
+  is not documented.
+
+Aliased as <tt>:not_new:</tt> and <tt>:not-new:</tt>.
+
+For Ruby code, but not for other RDoc sources,
+there is a shorthand for <tt>:stopdoc:</tt> and <tt>:startdoc:</tt>:
+
+  # Documented.
+  #--
+  # Not documented.
+  #++
+  # Documented.
+
+For C code, any of directives <tt>:startdoc:</tt>, <tt>:stopdoc:</tt>,
+and <tt>:enddoc:</tt> may appear in a stand-alone comment:
+
+  /* :startdoc: */
+  /* :stopdoc: */
+  /* :enddoc: */
+
+=== Directive for Specifying RDoc Source Format
+
+==== <tt>:markup:</tt>
+
+- Appears on a line by itself; takes argument +format+ (<tt>:markup: _format_</tt>).
+- Specifies the format for the RDoc input;
+  argument +format+ is one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
+
+=== Directives for Method Documentation
+
+==== <tt>:call-seq:</tt>
+
+- Appears on a line by itself.
+- Specifies the calling sequence to be reported in the HTML,
+  overriding the actual calling sequence in the code.
+  See RDoc::Example#call_seq_example for a demonstration.
+
+Note that RDoc can build the calling sequence for a Ruby-coded method,
+but not for other languages.
+You may want to override that by explicitly giving a <tt>:call-seq:</tt>
+directive if you want to include:
+
+- A return type, which is not automatically inferred.
+- Multiple calling sequences.
+
+For C code, the directive may appear in a stand-alone comment.
+
+==== <tt>:args:</tt>
+
+- Appears on a line by itself; takes argument +arg_names+ (<tt>:args: _arg_names_</tt>).
+- Specifies the arguments to be reported in the HTML,
+  overriding the actual arguments in the code.
+  See RDoc::Example#args_example for a demonstration.
+
+Aliased as <tt>:arg:</tt>.
+
+==== <tt>:yields:</tt>
+
+- Appears on a line by itself; takes argument +arg_names+ (<tt>:yields: _arg_names_</tt>).
+- Specifies the yield arguments to be reported in the HTML,
+  overriding the actual yield in the code.
+  See RDoc::Example#yields_example for a demonstration.
+
+Aliased as <tt>:yield:</tt>.
+
+=== Directives for Organizing Documentation
+
+By default, RDoc groups:
+
+- Singleton methods together in alphabetical order.
+- Instance methods and their aliases together in alphabetical order.
+- Attributes and their aliases together in alphabetical order.
+
+You can use directives to modify those behaviors.
+
+==== <tt>:section:</tt>
+
+- Appears on a line by itself; takes argument +section_title+ (<tt>:section: _section_title_</tt>).
+- Specifies that following methods are to be grouped into the section
+  with the given +section_title+,
+  or into the default section if no title is given.
+  The directive remains in effect until another such directive is given,
+  but may be temporarily overridden by directive <tt>:category:</tt>.
+  See below.
+
+The comment block containing this directive:
+
+- Must be separated by a blank line from the documentation for the next item.
+- May have one or more lines preceding the directive.
+  These will be removed, along with any trailing lines that match them.
+  Such lines may be visually helpful.
+- Lines of text that are not so removed become the descriptive text
+  for the section.
+
+Example:
+
+  # ----------------------------------------
+  # :section: My Section
+  # This is the section that I wrote.
+  # See it glisten in the noon-day sun.
+  # ----------------------------------------
+
+  ##
+  # Comment for some_method
+  def some_method
+    # ...
+  end
+
+You can use directive <tt>:category:</tt> to temporarily
+override the current section.
+
+==== <tt>:category:</tt>
+
+- Appears on a line by itself; takes argument +section_title+ (<tt>:category: _section_title_</tt>).
+- Specifies that just one following method is to be included
+  in the given section, or in the default section if no title is given.
+  Subsequent methods are to be grouped into the current section.
+
+=== Directive for Including a File
+
+==== <tt>:include:</tt>
+
+- Appears on a line by itself; takes argument +filepath+ (<tt>:include: _filepath_</tt>).
+- Specifies that the contents of the given file
+  are to be included at this point.
+
+The file content is shifted to have the same indentation as the colon
+at the start of the directive.
+
+The file is searched for in the directory containing the current file,
+and then in each of the directories given with the <tt>--include</tt>
+command-line option.
+
+For C code, the directive may appear in a stand-alone comment.
+
+== Text Markup
+
+Text markup is metatext that affects HTML rendering:
+
+- {Typeface}[rdoc-ref:rdoc@Typeface+Markup]: italic, bold, monofont.
+- {Character conversions}[rdoc-ref:rdoc@Character+Conversions]: copyright, trademark, certain punctuation.
+- {Links}[rdoc-ref:rdoc@Links].
+- {Escapes}[rdoc-ref:rdoc@Escaping+Text]: marking text as "not markup."
+
+=== Typeface Markup
+
+Typeface markup can specify that text is to be rendered
+as italic, bold, or monofont.
+
+Typeface markup may contain only one type of nested block:
+
+- More typeface markup:
+  {italic}[rdoc-ref:rdoc@Italic], {bold}[rdoc-ref:rdoc@Bold], {monofont}[rdoc-ref:rdoc@Monofont].
+
+==== Italic
+
+Text may be marked as italic via HTML tag <tt><i></tt> or <tt><em></tt>.
+
+Example input:
+
+  <i>Italicized words</i> in a paragraph.
+
+  <i>Italicized passage containing *bold* and +monofont+.</i>
+
+Rendered HTML:
+>>>
+  <i>Italicized words</i> in a paragraph.
+
+  <i>Italicized passage containing *bold* and +monofont+.</i>
+
+A single word may be italicized via a shorthand:
+prefixed and suffixed underscores.
+
+Example input:
+
+  _Italic_ in a paragraph.
+
+Rendered HTML:
+>>>
+  _Italic_ in a paragraph.
+
+==== Bold
+
+Text may be marked as bold via HTML tag <tt><b></tt>.
+
+Example input:
+
+  <b>Bold words</b> in a paragraph.
+
+  <b>Bold passage containing _italics_ and +monofont+.</b>
+
+Rendered HTML:
+
+>>>
+  <b>Bold words</b> in a paragraph.
+
+  <b>Bold passage containing _italics_ and +monofont+.</b>
+
+A single word may be made bold via a shorthand:
+prefixed and suffixed asterisks.
+
+Example input:
+
+  *Bold* in a paragraph.
+
+Rendered HTML:
+
+>>>
+  *Bold* in a paragraph.
+
+==== Monofont
+
+Text may be marked as monofont
+-- sometimes called 'typewriter font' --
+via HTML tag <tt><tt></tt> or <tt><code></tt>.
+
+Example input:
+
+  <tt>Monofont words</tt> in a paragraph.
+
+  <tt>Monofont passage containing _italics_ and *bold*.</tt>
+
+Rendered HTML:
+
+>>>
+  <tt>Monofont words</tt> in a paragraph.
+
+  <tt>Monofont passage containing _italics_ and *bold*.</tt>
+
+A single word may be made monofont by a shorthand:
+prefixed and suffixed plus-signs.
+
+Example input:
+
+  +Monofont+ in a paragraph.
+
+Rendered HTML:
+
+>>>
+  +Monofont+ in a paragraph.
+
+=== Character Conversions
+
+Certain combinations of characters may be converted to special characters;
+whether the conversion occurs depends on whether the special character
+is available in the current encoding.
+
+- <tt>(c)</tt> converts to (c) (copyright character); must be lowercase.
+
+- <tt>(r)</tt> converts to (r) (registered trademark character); must be lowercase.
+
+- <tt>'foo'</tt> converts to 'foo' (smart single-quotes).
+
+- <tt>"foo"</tt> converts to "foo" (smart double-quotes).
+
+- <tt>foo ... bar</tt> converts to foo ... bar (1-character ellipsis).
+
+- <tt>foo -- bar</tt> converts to foo -- bar (1-character en-dash).
+
+- <tt>foo --- bar</tt> converts to foo --- bar (1-character em-dash).
+
+== Links
+
+Certain strings in RDoc text are converted to links.
+Any such link may be suppressed by prefixing a backslash.
+This section shows how to link to various targets.
+
+=== Class Links
+
+- On-page: <tt>RDoc::Example::ExampleClass</tt> links to RDoc::Example::ExampleClass.
+- Off-page: <tt>RDoc::Alias</tt> links to RDoc::Alias.
+
+Note: When marking up code (such as class, module,
+constant, and method) as "<tt>+code+</tt>" (for interoperability
+with other Markdown parsers mainly), any word that refers to a known
+code object, and is marked up entirely and separately as "monofont",
+is also converted to a link.
+
+- <tt>+RDoc+</tt> links to +RDoc+.
+
+=== Module Links
+
+- On-page: <tt>RDoc::Example::ExampleModule</tt> links to RDoc::Example::ExampleModule.
+- Off-page: <tt>RDoc</tt> links to RDoc.
+
+=== Constant Links
+
+- On-page: <tt>RDoc::Example::EXAMPLE_CONSTANT</tt> links to RDoc::Example::EXAMPLE_CONSTANT.
+- Off-page: <tt>RDoc::Text::MARKUP_FORMAT</tt> links to RDoc::Text::MARKUP_FORMAT.
+
+=== Singleton Method Links
+
+- On-page: <tt>RDoc::Example::singleton_method_example</tt> links to RDoc::Example::singleton_method_example.
+- Off-page: <tt>RDoc::TokenStream::to_html</tt> links to RDoc::TokenStream::to_html.
+
+Note: Occasionally RDoc is not linked to a method whose name
+has only special characters. Check whether the links you were expecting
+are actually there. If not, you'll need to put in an explicit link;
+see below.
+
+Pro tip: The link to any method is available in the alphabetical table of contents
+at the top left of the page for the class or module.
+
+=== Instance Method Links
+
+- On-page: <tt>#instance_method_example</tt> links to #instance_method_example
+  (when in the same class context).
+- Off-page: <tt>RDoc::Alias#html_name</tt> links to RDoc::Alias#html_name.
+
+See the Note and Pro Tip immediately above.
+
+=== Attribute Links
+
+- Off-page: <tt>RDoc::Alias#name</tt> links to RDoc::Alias#name.
+
+=== Alias Links
+
+- Off-page: <tt>RDoc::Alias#new_name</tt> links to RDoc::Alias#new_name.
+
+=== Protocol Links
+
+[Protocol +http+]
+
+  - Linked: <tt>http://yahoo.com</tt> links to http://yahoo.com.
+
+[Protocol +https+]
+
+  - Linked: <tt>https://github.com</tt> links to https://github.com.
+
+[Protocol +ftp+]
+
+  - Linked: <tt>ftp://nosuch.site</tt> links to ftp://nosuch.site.
+
+[Protocol +mailto+]
+
+  - Linked: <tt>mailto:foo@bar.com</tt> links to mailto:foo@bar.com.
+
+[Protocol +irc+]
+
+  - Link: <tt>irc://irc.freenode.net/ruby</tt> links to irc://irc.freenode.net/ruby.
+
+=== Image Filename Extensions
+
+Link: <tt>https://www.ruby-lang.org/images/header-ruby-logo@2x.png</tt> is
+converted to an in-line HTML +img+ tag, which displays the image in the HTML:
+
+https://www.ruby-lang.org/images/header-ruby-logo@2x.png
+
+Also works for +bmp+, +gif+, +jpeg+, and +jpg+ files.
+
+Note: Works only for a fully qualified URL.
+
+=== Heading Links
+
+Link: <tt>RDoc::RD@LICENSE</tt> links to RDoc::RDoc::RD@LICENSE.
+
+Note that spaces in the actual heading are represented by <tt>+</tt> characters
+in the linkable text.
+
+- Link: <tt>RDoc::Options@Saved+Options</tt> links to RDoc::Options@Saved+Options.
+
+Punctuation and other special characters must be escaped like CGI.escape.
+
+Pro tip: The link to any heading is available in the alphabetical table of contents
+at the top left of the page for the class or module.
+
+=== Section Links
+
+See Directives for Organizing Documentation above.
+
+- Link: <tt>RDoc::Markup::ToHtml@Visitor</tt> links to RDoc::Markup::ToHtml@Visitor.
+
+If a section and a heading share the same name, the link target is the section.
+
+=== Single-Word Text Link
+
+Use square brackets to create single-word text link:
+
+- <tt>GitHub[https://github.com]</tt> links to GitHub[https://github.com].
+
+=== Multi-Word Text Link
+
+Use square brackets and curly braces to create a multi-word text link.
+
+- <tt>{GitHub home page}[https://github.com]</tt> links to
+  {GitHub home page}[https://github.com].
+
+=== <tt>rdoc-ref</tt> Scheme
+
+A link with the <tt>rdoc-ref:</tt> scheme links to the referenced item,
+if that item exists.
+The referenced item may be a class, module, method, file, etc.
+
+- Class: <tt>Alias[rdoc-ref:RDoc::Alias]</tt> generates Alias[rdoc-ref:RDoc::Alias].
+- Module: <tt>RDoc[rdoc-ref:RDoc]</tt> generates RDoc[rdoc-ref:RDoc].
+- Method: <tt>foo[rdoc-ref:RDoc::Example#instance_method_example]</tt>
+  generates foo[rdoc-ref:RDoc::Example#instance_method_example].
+- Constant: <tt>bar[rdoc-ref:RDoc::Example::EXAMPLE_CONSTANT]</tt>
+  generates bar[rdoc-ref:RDoc::Example::EXAMPLE_CONSTANT].
+- File: <tt>README[rdoc-ref:README.md]</tt> generates README[rdoc-ref:README.md].
+
+If the referenced item does not exist, no link is generated
+and entire <tt>rdoc-ref:</tt> square-bracketed clause is removed
+from the resulting text.
+
+- <tt>Nosuch[rdoc-ref:RDoc::Nosuch]</tt> generates Nosuch.
+
+=== <tt>rdoc-label</tt> Scheme
+
+==== Simple
+
+You can specify a link target using this form,
+where the second part cites the id of an HTML element.
+
+This link refers to the constant +EXAMPLE_CONSTANT+ on this page:
+
+- <tt>{EXAMPLE_CONSTANT}[rdoc-label:EXAMPLE_CONSTANT]</tt>
+
+==== With Return
+
+You can specify both a link target and a local label
+that can be used as the target for a return link.
+These two links refer to each other:
+
+- <tt>{go to addressee}[rdoc-label:addressee:sender]</tt>
+- <tt>{return to sender}[rdoc-label:sender:addressee]</tt>
+
+Thus:
+
+{go to addressee}[rdoc-label:addressee:sender]
+
+Some text.
+
+{return to sender}[rdoc-label:sender:addressee]
+
+=== <tt>link:</tt> Scheme
+
+- <tt>link:README_md.html</tt> links to link:README_md.html.
+
+=== <tt>rdoc-image</tt> Scheme
+
+Use the <tt>rdoc-image</tt> scheme to display an image that is also a link:
+
+  {rdoc-image:path/to/image}[link_target]
+
+- Link: <tt>{rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]</tt>
+  displays image <tt>https://www.ruby-lang.org/images/header-ruby-logo@2x.png</tt>
+  as a link to <tt>https://www.ruby-lang.org</tt>.
+
+  {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]
+
+A relative path as the target also works:
+
+- Link: <tt>{rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html]</tt> links to <tt>./Alias.html</tt>
+
+  {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html]
+
+== Escaping Text
+
+Text that would otherwise be interpreted as markup
+can be "escaped," so that it is not interpreted as markup;
+the escape character is the backslash (<tt>'\\'</tt>).
+
+In a verbatim text block or a code block,
+the escape character is always preserved:
+
+Example input:
+
+  This is not verbatim text.
+
+    This is verbatim text, with an escape character \.
+
+  This is not a code block.
+
+    def foo
+      'String with an escape character.'
+    end
+
+Rendered HTML:
+
+>>>
+  This is not verbatim text.
+
+    This is verbatim text, with an escape character \.
+
+  This is not a code block.
+
+    def foo
+      'This is a code block with an escape character \.'
+    end
+
+In typeface markup (italic, bold, or monofont),
+an escape character is preserved unless it is immediately
+followed by nested typeface markup.
+
+Example input:
+
+  This list is about escapes; it contains:
+
+  - <tt>Monofont text with unescaped nested _italic_</tt>.
+  - <tt>Monofont text with escaped nested \_italic_</tt>.
+  - <tt>Monofont text with an escape character \</tt>.
+
+Rendered HTML:
+
+>>>
+  This list is about escapes; it contains:
+
+  - <tt>Monofont text with unescaped nested _italic_</tt>.
+  - <tt>Monofont text with escaped nested \_italic_</tt>.
+  - <tt>Monofont text with an escape character \ </tt>.
+
+In other text-bearing blocks
+(paragraphs, block quotes, list items, headings):
+
+- A single escape character immediately followed by markup
+  escapes the markup.
+- A single escape character followed by whitespace is preserved.
+- A single escape character anywhere else is ignored.
+- A double escape character is rendered as a single backslash.
+
+  Example input:
+
+    This list is about escapes; it contains:
+
+    - An unescaped class name, RDoc, that will become a link.
+    - An escaped class name, \RDoc, that will not become a link.
+    - An escape character followed by whitespace \ .
+    - An escape character \that is ignored.
+    - A double escape character \\ that is rendered
+      as a single backslash.
+
+  Rendered HTML:
+
+  >>>
+    This list is about escapes; it contains:
+
+    - An unescaped class name, RDoc, that will become a link.
+    - An escaped class name, \RDoc, that will not become a link.
+    - An escape character followed by whitespace \ .
+    - An escape character \that is ignored.
+    - A double escape character \\ that is rendered
+      as a single backslash.
+
+== Derived Documentation
+
+RDoc can automatically derive documentation from Ruby code.
+For demonstrations, see RDoc::Example.
+
+=== Class
+
+By default, RDoc documents:
+
+- Class name.
+- Parent class.
+- Included modules.
+- Singleton methods.
+- Instance methods.
+- Aliases.
+- Constants.
+- Attributes.
+
+=== Module
+
+By default, RDoc documents:
+
+- Module name.
+- Included modules.
+- Singleton methods.
+- Instance methods.
+- Aliases.
+- Constants.
+- Attributes.
+
+=== Method
+
+By default, RDoc documents:
+
+- Method name.
+- Arguments.
+- Yielded values.
+
+See RDoc::Example#derived_docs_example.
+
+=== Alias
+
+By default, RDoc documents:
+
+- Alias name.
+- Aliased name.
+
+See RDoc::Example#aliased_method.
+
+=== Constant
+
+By default, RDoc documents:
+
+- Constant name.
+
+See RDoc::Example::EXAMPLE_CONSTANT.
+
+=== Attribute
+
+By default, RDoc documents:
+
+- Attribute name.
+- Attribute type (<tt>[R]</tt>, <tt>[W]</tt>, or <tt>[RW]</tt>)
+
+See RDoc::Example#example_attribute.
diff --git a/doc/rdoc/example.rb b/doc/rdoc/example.rb
new file mode 100644
index 0000000000..7df8d99b00
--- /dev/null
+++ b/doc/rdoc/example.rb
@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'rdoc'
+
+##
+# RDoc::Example provides example Ruby code objects for demonstrating
+# RDoc's documentation capabilities.
+#
+# This class is used by:
+# - bin/console for interactive exploration of RDoc objects
+# - Testing cross-reference link generation
+# - Demonstrating Ruby-specific directives like :call-seq:, :args:, :yields:
+#
+# For comprehensive RDoc markup documentation, see doc/markup_reference/rdoc.rdoc.
+
+class RDoc::Example
+
+  # Example class for demonstrating cross-reference links.
+  class ExampleClass; end
+
+  # Example module for demonstrating cross-reference links.
+  module ExampleModule; end
+
+  # Example singleton method.
+  def self.singleton_method_example(foo, bar); end
+
+  # Example instance method.
+  #
+  # This method demonstrates how RDoc documents instance methods,
+  # including arguments and yield parameters.
+  def instance_method_example(foo, bar)
+    yield 'baz'
+  end
+
+  alias aliased_method instance_method_example
+
+  # Example attribute.
+  attr_accessor :example_attribute
+
+  alias aliased_attribute example_attribute
+
+  # Example constant.
+  EXAMPLE_CONSTANT = ''
+
+  # :call-seq:
+  #   call_seq_example(foo, bar)
+  #   Can be anything -> bar
+  #   Also anything more -> baz or bat
+  #
+  # The <tt>:call-seq:</tt> directive overrides the actual calling sequence
+  # found in the Ruby code.
+  #
+  # - It can specify anything at all.
+  # - It can have multiple calling sequences.
+  #
+  # Note that the "arrow" is two characters, hyphen and right angle-bracket,
+  # which is made into a single character in the HTML.
+  #
+  # Here is the <tt>:call-seq:</tt> directive given for this method:
+  #
+  #   :call-seq:
+  #     call_seq_example(foo, bar)
+  #     Can be anything -> bar
+  #     Also anything more -> baz or bat
+  #
+  def call_seq_example
+    nil
+  end
+
+  # The <tt>:args:</tt> directive overrides the actual arguments
+  # found in the Ruby code.
+  #
+  # The actual signature is +args_example(foo, bar)+, but the directive
+  # makes it appear as +args_example(baz)+.
+  #
+  def args_example(foo, bar) # :args: baz
+    nil
+  end
+
+  # The <tt>:yields:</tt> directive overrides the actual yield
+  # found in the Ruby code.
+  #
+  # The actual yield is +'baz'+, but the directive makes it appear
+  # as +'bat'+.
+  #
+  def yields_example(foo, bar) # :yields: 'bat'
+    yield 'baz'
+  end
+
+  # This method is documented only by RDoc's derived documentation,
+  # except for these comments.
+  #
+  # RDoc automatically extracts:
+  # - Method name
+  # - Arguments
+  # - Yielded values
+  #
+  def derived_docs_example(foo, bar)
+    yield 'baz'
+  end
+
+end
diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb
deleted file mode 100644
index 1729144f4c..0000000000
--- a/doc/rdoc/markup_reference.rb
+++ /dev/null
@@ -1,1308 +0,0 @@
-require 'rdoc'
-
-# This page is about RDoc's +rdoc+ input format,
-# which here we'll call "RDoc markup" or simply "markup."
-#
-# == About This \Class
-#
-# \Class \RDoc::MarkupReference exists only to provide a suitable home
-# for a reference document for \RDoc markup.
-#
-# All objects defined in this class -- classes, modules, methods, aliases,
-# attributes, and constants -- are solely for illustrating \RDoc markup,
-# and have no other legitimate use.
-#
-# == About the Examples
-#
-# - Examples in this reference are Ruby code and comments;
-#   certain differences from other sources
-#   (such as C code and comments) are noted.
-# - Almost all examples on this page are all RDoc-like;
-#   that is, they have no explicit comment markers like Ruby <tt>#</tt>
-#   or C <tt>/* ... */</tt>.
-# - An example that shows rendered HTML output
-#   displays that output in a blockquote:
-#
-#   >>>
-#     Some stuff
-#
-# == Markup Sources
-#
-# The sources of markup documentation vary according to the type of file:
-#
-# - <tt>.rb</tt> (Ruby code file):
-#
-#   - Markup may be found in Ruby comments:
-#     A comment that immediately precedes the definition
-#     of a Ruby class, module, method, alias, constant, or attribute
-#     becomes the documentation for that defined object.
-#   - A markup directive may be found in:
-#
-#     - A trailing comment (on the same line as code);
-#       see <tt>:nodoc:</tt>, <tt>:doc:</tt>, and <tt>:notnew:</tt>.
-#     - A single-line comment;
-#       see other {Directives}[rdoc-ref:RDoc::MarkupReference@Directives].
-#
-#   - Documentation may be derived from the Ruby code itself;
-#     see {Derived Documentation}[rdoc-ref:RDoc::MarkupReference@Derived+Documentation].
-#
-# - <tt>.c</tt> (C code file): markup is parsed from C comments.
-#   A comment that immediately precedes
-#   a function that implements a Ruby method,
-#   or otherwise immediately precedes the definition of a Ruby object,
-#   becomes the documentation for that object.
-# - <tt>.rdoc</tt> (markup file):
-#   markup is parsed from the entire file.
-#   The text is not associated with any code object,
-#   but may (depending on how the documentation is built)
-#   become a separate page.
-#
-# Note that all of the above applies to \RDoc <tt>markup</tt>-formatted documentation:
-#
-# - A C- or \Ruby-coded file may contain <tt>markdown</tt>-formatted documentation,
-#   though that format must be declared (because the default is +markup+).
-# - A markdown (<tt>.md</tt>) file contains only <tt>markdown</tt>-formatted documentation.
-#
-# == Markup Document
-#
-# The term <i>markup document</i> refers to one of:
-#
-# - A (possibly multi-line) comment in a Ruby or C file
-#   that generates documentation (as above).
-# - An entire markup file (i.e., a file with extension <tt>.rdoc</tt>).
-#
-# == Blocks
-#
-# It's convenient to think of an \RDoc document as a sequence of _blocks_
-# of various types (details at the links):
-#
-# - {Paragraph}[rdoc-ref:RDoc::MarkupReference@Paragraphs]:
-#   an ordinary paragraph.
-# - {Verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks]:
-#   a block of text to be rendered literally.
-# - {Code block}[rdoc-ref:RDoc::MarkupReference@Code+Blocks]:
-#   a verbatim text block containing Ruby code,
-#   to be rendered with code highlighting.
-# - {Block quote}[rdoc-ref:RDoc::MarkupReference@Block+Quotes]:
-#   a longish quoted passage, to be rendered with indentation
-#   instead of quote marks.
-# - {List}[rdoc-ref:RDoc::MarkupReference@Lists]: items for
-#   a bullet list, numbered list, lettered list, or labeled list.
-# - {Heading}[rdoc-ref:RDoc::MarkupReference@Headings]:
-#   a heading.
-# - {Horizontal rule}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules]:
-#   a line across the rendered page.
-# - {Directive}[rdoc-ref:RDoc::MarkupReference@Directives]:
-#   various special directions for the rendering.
-# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup]:
-#   text to be rendered in a special way.
-#
-# About the blocks:
-#
-# - Except for a paragraph, a block is distinguished by its indentation,
-#   or by unusual initial or embedded characters.
-# - Any block may appear independently
-#   (that is, not nested in another block);
-#   some blocks may be nested, as detailed below.
-# - In a multi-line block,
-#   \RDoc looks for the block's natural left margin,
-#   which becomes the <em>base margin</em> for the block
-#   and is the initial <em>current margin</em> for the block.
-#
-# === Paragraphs
-#
-# A paragraph consists of one or more non-empty lines of ordinary text,
-# each beginning at the current margin.
-#
-# Note: Here, <em>ordinary text</em> means text that is <em>not identified</em>
-# by indentation, or by unusual initial or embedded characters.
-# See below.
-#
-# Paragraphs are separated by one or more empty lines.
-#
-# Example input:
-#
-#   \RDoc produces HTML and command-line documentation for Ruby projects.
-#   \RDoc includes the rdoc and ri tools for generating and displaying
-#   documentation from the command-line.
-#
-#   You'll love it.
-#
-# Rendered HTML:
-# >>>
-#   \RDoc produces HTML and command-line documentation for Ruby projects.
-#   \RDoc includes the rdoc and ri tools for generating and displaying
-#   documentation from the command-line.
-#
-#   You'll love it.
-#
-# A paragraph may contain nested blocks, including:
-#
-# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
-# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
-# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes].
-# - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists].
-# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
-# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
-# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
-#
-# === Verbatim Text Blocks
-#
-# Text indented farther than the current margin becomes a <em>verbatim text block</em>
-# (or a code block, described next).
-# In the rendered HTML, such text:
-#
-# - Is indented.
-# - Has a contrasting background color.
-#
-# The verbatim text block ends at the first line beginning at the current margin.
-#
-# Example input:
-#
-#   This is not verbatim text.
-#
-#     This is verbatim text.
-#       Whitespace is honored.     # See?
-#         Whitespace is honored.     # See?
-#
-#     This is still the same verbatim text block.
-#
-#   This is not verbatim text.
-#
-# Rendered HTML:
-# >>>
-#   This is not verbatim text.
-#
-#     This is verbatim text.
-#       Whitespace is honored.     # See?
-#         Whitespace is honored.     # See?
-#
-#     This is still the same verbatim text block.
-#
-#   This is not verbatim text.
-#
-# A verbatim text block may not contain nested blocks of any kind
-# -- it's verbatim.
-#
-# === Code Blocks
-#
-# A special case of verbatim text is the <em>code block</em>,
-# which is merely verbatim text that \RDoc recognizes as Ruby code:
-#
-# In the rendered HTML, the code block:
-#
-# - Is indented.
-# - Has a contrasting background color.
-# - Has syntax highlighting.
-#
-# Example input:
-#
-#   Consider this method:
-#
-#     def foo(name = '', value = 0)
-#       @name = name      # Whitespace is still honored.
-#       @value = value
-#     end
-#
-#
-# Rendered HTML:
-# >>>
-#   Consider this method:
-#
-#     def foo(name = '', value = 0)
-#       @name = name      # Whitespace is still honored.
-#       @value = value
-#     end
-#
-# Pro tip:  If your indented Ruby code does not get highlighted,
-# it may contain a syntax error.
-#
-# A code block may not contain nested blocks of any kind
-# -- it's verbatim.
-#
-# === Block Quotes
-#
-# You can use the characters <tt>>>></tt> (unindented),
-# followed by indented text, to treat the text
-# as a {block quote}[https://en.wikipedia.org/wiki/Block_quotation]:
-#
-# Example input:
-#
-#   Here's a block quote:
-#   >>>
-#     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
-#     commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
-#     Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.
-#
-#     Aenean congue ligula eu ligula molestie, eu pellentesque purus
-#     faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
-#     diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
-#     purus magna ut tortor.
-#
-# Rendered HTML:
-#
-# >>>
-#   Here's a block quote:
-#   >>>
-#     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
-#     commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
-#     Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.
-#
-#     Aenean congue ligula eu ligula molestie, eu pellentesque purus
-#     faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
-#     diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
-#     purus magna ut tortor.
-#
-# Note that, unlike verbatim text, single newlines are not honored,
-# but that a double newline begins a new paragraph in the block quote.
-#
-# A block quote may contain nested blocks, including:
-#
-# - Other block quotes.
-# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs].
-# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
-# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
-# - {Lists}[rdoc-ref:RDoc::MarkupReference@Lists].
-# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
-# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
-# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
-#
-# === Lists
-#
-# Each type of list item is marked by a special beginning:
-#
-# - Bullet list item: Begins with a hyphen or asterisk.
-# - Numbered list item: Begins with digits and a period.
-# - Lettered list item: Begins with an alphabetic character and a period.
-# - Labeled list item: Begins with one of:
-#   - Square-bracketed text.
-#   - A word followed by two colons.
-#
-# A list begins with a list item and continues, even across blank lines,
-# as long as list items of the same type are found at the same indentation level.
-#
-# A new list resets the current margin inward.
-# Additional lines of text aligned at that margin
-# are part of the continuing list item.
-#
-# A list item may be continued on additional lines that are aligned
-# with the first line.  See examples below.
-#
-# A list item may contain nested blocks, including:
-#
-# - Other lists of any type.
-# - {Paragraphs}[rdoc-ref:RDoc::MarkupReference@Paragraphs].
-# - {Verbatim text blocks}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks].
-# - {Code blocks}[rdoc-ref:RDoc::MarkupReference@Code+Blocks].
-# - {Block quotes}[rdoc-ref:RDoc::MarkupReference@Block+Quotes].
-# - {Headings}[rdoc-ref:RDoc::MarkupReference@Headings].
-# - {Horizontal rules}[rdoc-ref:RDoc::MarkupReference@Horizontal+Rules].
-# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
-#
-# ==== Bullet Lists
-#
-# A bullet list item begins with a hyphen or asterisk.
-#
-# Example input:
-#
-#   - An item.
-#   - Another.
-#   - An item spanning
-#     multiple lines.
-#
-#   * Yet another.
-#   - Last one.
-#
-# Rendered HTML:
-# >>>
-#   - An item.
-#   - Another.
-#   - An item spanning
-#     multiple lines.
-#
-#   * Yet another.
-#   - Last one.
-#
-# ==== Numbered Lists
-#
-# A numbered list item begins with digits and a period.
-#
-# The items are automatically re-numbered.
-#
-# Example input:
-#
-#   100. An item.
-#   10. Another.
-#   1. An item spanning
-#      multiple lines.
-#
-#   1. Yet another.
-#   1000. Last one.
-#
-# Rendered HTML:
-# >>>
-#   100. An item.
-#   10. Another.
-#   1. An item spanning
-#      multiple lines.
-#
-#   1. Yet another.
-#   1000. Last one.
-#
-# ==== Lettered Lists
-#
-# A lettered list item begins with letters and a period.
-#
-# The items are automatically "re-lettered."
-#
-# Example input:
-#
-#   z. An item.
-#   y. Another.
-#   x. An item spanning
-#      multiple lines.
-#
-#   x. Yet another.
-#   a. Last one.
-#
-# Rendered HTML:
-# >>>
-#   z. An item.
-#   y. Another.
-#
-#   x. Yet another.
-#   a. Last one.
-#
-# ==== Labeled Lists
-#
-# A labeled list item begins with one of:
-#
-# - Square-bracketed text: the label and text are on two lines.
-# - A word followed by two colons: the label and text are on the same line.
-#
-# Example input:
-#
-#   [foo] An item.
-#   bat:: Another.
-#   [bag] An item spanning
-#         multiple lines.
-#
-#   [bar baz] Yet another.
-#   bam:: Last one.
-#
-# Rendered HTML:
-# >>>
-#   [foo] An item.
-#   bat:: Another.
-#   [bag] An item spanning
-#         multiple lines.
-#
-#   [bar baz] Yet another.
-#   bam:: Last one.
-#
-# === Headings
-#
-# A heading begins with up to six equal-signs, followed by heading text.
-# Whitespace between those and the heading text is optional.
-#
-# Examples:
-#
-#   = Section 1
-#   == Section 1.1
-#   === Section 1.1.1
-#   === Section 1.1.2
-#   == Section 1.2
-#   = Section 2
-#   = Foo
-#   == Bar
-#   === Baz
-#   ==== Bam
-#   ===== Bat
-#   ====== Bad
-#   ============Still a Heading (Level 6)
-#   \== Not a Heading
-#
-# A heading may contain only one type of nested block:
-#
-# - {Text Markup}[rdoc-ref:RDoc:MarkupReference@Text+Markup].
-#
-# === Horizontal Rules
-#
-# A horizontal rule consists of a line with three or more hyphens
-# and nothing more.
-#
-# Example input:
-#
-#   ---
-#   --- Not a horizontal rule.
-#
-#   -- Also not a horizontal rule.
-#   ---
-#
-# Rendered HTML:
-# >>>
-#   ---
-#   --- Not a horizontal rule.
-#
-#   -- Also not a horizontal rule.
-#   ---
-#
-# === Directives
-#
-# ==== Directives for Allowing or Suppressing Documentation
-#
-# ====== <tt>:stopdoc:</tt>
-#
-# - Appears on a line by itself.
-# - Specifies that \RDoc should ignore markup
-#   until next <tt>:startdoc:</tt> directive or end-of-file.
-#
-# ====== <tt>:startdoc:</tt>
-#
-# - Appears on a line by itself.
-# - Specifies that \RDoc should resume parsing markup.
-#
-# ====== <tt>:enddoc:</tt>
-#
-# - Appears on a line by itself.
-# - Specifies that \RDoc should ignore markup to end-of-file
-#   regardless of other directives.
-#
-# ====== <tt>:nodoc:</tt>
-#
-# - Appended to a line of code
-#   that defines a class, module, method, alias, constant, or attribute;
-#   takes optional argument +all+ (<tt>:nodoc: all</tt>).
-# - Specifies that the defined object should not be documented.
-#
-# For a method definition in C code, it the directive must be in the comment line
-# immediately preceding the definition:
-#
-#   /* :nodoc: */
-#   static VALUE
-#   some_method(VALUE self)
-#   {
-#     return self;
-#   }
-#
-# Note that this directive has <em>no effect at all</em>
-# when placed at the method declaration:
-#
-#   /* :nodoc: */
-#   rb_define_method(cMyClass, "do_something", something_func, 0);
-#
-# The above comment is just a comment and has nothing to do with \RDoc.
-# Therefore, +do_something+ method will be reported as "undocumented"
-# unless that method or function is documented elsewhere.
-#
-# For a constant definition in C code, this directive <em>can not work</em>
-# because there is no "implementation" place for a constant.
-#
-# With argument +all+ (<tt>:nodoc: all</tt>),
-# specifies that the class or module should not be documented.
-# By default, however, a nested class or module _will_ be documented.
-#
-# ====== <tt>:doc:</tt>
-#
-# - Appended to a line of code
-#   that defines a class, module, method, alias, constant, or attribute.
-# - Specifies the defined object should be documented, even if it otherwise
-#   would not be documented.
-#
-# ====== <tt>:notnew:</tt>
-#
-# - Appended to a line of code
-#   that defines instance method +initialize+.
-# - Specifies that singleton method +new+ should not be documented.
-#   By default, Ruby fakes a corresponding singleton method +new+,
-#   which \RDoc includes in the documentation.
-#   Note that instance method +initialize+ is private, and so by default
-#   is not documented.
-#
-# Aliased as <tt>:not_new:</tt> and <tt>:not-new:</tt>.
-#
-# For Ruby code, but not for other \RDoc sources,
-# there is a shorthand for <tt>:stopdoc:</tt> and <tt>:startdoc:</tt>:
-#
-#   # Documented.
-#   #--
-#   # Not documented.
-#   #++
-#   # Documented.
-#
-# For C code, any of directives <tt>:startdoc:</tt>, <tt>:stopdoc:</tt>,
-# and <tt>:enddoc:</tt> may appear in a stand-alone comment:
-#
-#   /* :startdoc: */
-#   /* :stopdoc: */
-#   /* :enddoc: */
-#
-# ==== Directive for Specifying \RDoc Source Format
-#
-# ====== <tt>:markup:</tt>
-#
-# - Appears on a line by itself; takes argument +format+ (<tt>:markup: _format_</tt>).
-# - Specifies the format for the \RDoc input;
-#   argument +format+ is one of: +rdoc+ (the default), +markdown+, +rd+, +tomdoc+.
-#   See {Markup Formats}[rdoc-ref:RDoc::Markup@Markup+Formats].
-#
-# ==== Directives for Method Documentation
-#
-# ====== <tt>:call-seq:</tt>
-#
-# - Appears on a line by itself.
-# - Specifies the calling sequence to be reported in the HTML,
-#   overriding the actual calling sequence in the code.
-#   See method #call_seq_directive.
-#
-# Note that \RDoc can build the calling sequence for a Ruby-coded method,
-# but not for other languages.
-# You may want to override that by explicitly giving a <tt>:call-seq:</tt>
-# directive if you want to include:
-#
-# - A return type, which is not automatically inferred.
-# - Multiple calling sequences.
-#
-# For C code, the directive may appear in a stand-alone comment.
-#
-# ====== <tt>:args:</tt>
-#
-# - Appears on a line by itself; takes argument +arg_names+ (<tt>:args: _arg_names_</tt>).
-# - Specifies the arguments to be reported in the HTML,
-#   overriding the actual arguments in the code.
-#   See method #args_directive.
-#
-# Aliased as <tt>:arg:</tt>.
-#
-# ====== <tt>:yields:</tt>
-#
-# - Appears on a line by itself; takes argument +arg_names+ (<tt>:yields: _arg_names_</tt>).
-# - Specifies the yield arguments to be reported in the HTML,
-#   overriding the actual yield in the code.
-#   See method #yields_directive.
-#
-# Aliased as <tt>:yield:</tt>.
-#
-# ==== Directives for Organizing Documentation
-#
-# By default, \RDoc groups:
-#
-# - Singleton methods together in alphabetical order.
-# - Instance methods and their aliases together in alphabetical order.
-# - Attributes and their aliases together in alphabetical order.
-#
-# You can use directives to modify those behaviors.
-#
-# ====== <tt>:section:</tt>
-#
-# - Appears on a line by itself; takes argument +section_title+ (<tt>:section: _section_title_</tt>).
-# - Specifies that following methods are to be grouped into the section
-#   with the given +section_title+,
-#   or into the default section if no title is given.
-#   The directive remains in effect until another such directive is given,
-#   but may be temporarily overridden by directive <tt>:category:</tt>.
-#   See below.
-#
-# The comment block containing this directive:
-#
-# - Must be separated by a blank line from the documentation for the next item.
-# - May have one or more lines preceding the directive.
-#   These will be removed, along with any trailing lines that match them.
-#   Such lines may be visually helpful.
-# - Lines of text that are not so removed become the descriptive text
-#   for the section.
-#
-# Example:
-#
-#   # ----------------------------------------
-#   # :section: My Section
-#   # This is the section that I wrote.
-#   # See it glisten in the noon-day sun.
-#   # ----------------------------------------
-#
-#   ##
-#   # Comment for some_method
-#   def some_method
-#     # ...
-#   end
-#
-# You can use directive <tt>:category:</tt> to temporarily
-# override the current section.
-#
-# ====== <tt>:category:</tt>
-#
-# - Appears on a line by itself; takes argument +section_title+ (<tt>:category: _section_title_</tt>).
-# - Specifies that just one following method is to be included
-#   in the given section, or in the default section if no title is given.
-#   Subsequent methods are to be grouped into the current section.
-#
-# ==== Directive for Including a File
-#
-# ====== <tt>:include:</tt>
-#
-# - Appears on a line by itself; takes argument +filepath+ (<tt>:include: _filepath_</tt>).
-# - Specifies that the contents of the given file
-#   are to be included at this point.
-#
-# The file content is shifted to have the same indentation as the colon
-# at the start of the directive.
-#
-# The file is searched for in the directory containing the current file,
-# and then in each of the directories given with the <tt>--include</tt>
-# command-line option.
-#
-# For C code, the directive may appear in a stand-alone comment
-#
-# === Text Markup
-#
-# Text markup is metatext that affects HTML rendering:
-#
-# - Typeface: italic, bold, monofont.
-# - Character conversions: copyright, trademark, certain punctuation.
-# - Links.
-# - Escapes: marking text as "not markup."
-#
-# ==== Typeface Markup
-#
-# Typeface markup can specify that text is to be rendered
-# as italic, bold, or monofont.
-#
-# Typeface markup may contain only one type of nested block:
-#
-# - More typeface markup:
-#   italic, bold, monofont.
-#
-# ===== Italic
-#
-# Text may be marked as italic via HTML tag <tt><i></tt> or <tt><em></tt>.
-#
-# Example input:
-#
-#   <i>Italicized words</i> in a paragraph.
-#
-#   >>>
-#     <i>Italicized words in a block quote</i>.
-#
-#   - <i>Italicized words</i> in a list item.
-#
-#   ====== <i>Italicized words</i> in a Heading
-#
-#   <i>Italicized passage containing *bold* and +monofont+.</i>
-#
-# Rendered HTML:
-# >>>
-#   <i>Italicized words</i> in a paragraph.
-#
-#   >>>
-#     <i>Italicized words in a block quote</i>.
-#
-#   - <i>Italicized words</i> in a list item.
-#
-#   ====== <i>Italicized words</i> in a Heading
-#
-#   <i>Italicized passage containing *bold* and +monofont+.</i>
-#
-# A single word may be italicized via a shorthand:
-# prefixed and suffixed underscores.
-#
-# Example input:
-#
-#   _Italic_ in a paragraph.
-#
-#   >>>
-#     _Italic_ in a block quote.
-#
-#   - _Italic_ in a list item.
-#
-#   ====== _Italic_ in a Heading
-#
-# Rendered HTML:
-# >>>
-#   _Italic_ in a paragraph.
-#
-#   >>>
-#     _Italic_ in a block quote.
-#
-#   - _Italic_ in a list item.
-#
-#   ====== _Italic_ in a Heading
-#
-# ===== Bold
-#
-# Text may be marked as bold via HTML tag <tt><b></tt>.
-#
-# Example input:
-#
-#   <b>Bold words</b> in a paragraph.
-#
-#   >>>
-#     <b>Bold words</b> in a block quote.
-#
-#   - <b>Bold words</b> in a list item.
-#
-#   ====== <b>Bold words</b> in a Heading
-#
-#   <b>Bold passage containing _italics_ and +monofont+.</b>
-#
-# Rendered HTML:
-#
-# >>>
-#   <b>Bold words</b> in a paragraph.
-#
-#   >>>
-#     <b>Bold words</b> in a block quote.
-#
-#   - <b>Bold words</b> in a list item.
-#
-#   ====== <b>Bold words</b> in a Heading
-#
-#   <b>Bold passage containing _italics_ and +monofont+.</b>
-#
-# A single word may be made bold via a shorthand:
-# prefixed and suffixed asterisks.
-#
-# Example input:
-#
-#   *Bold* in a paragraph.
-#
-#   >>>
-#     *Bold* in a block quote.
-#
-#   - *Bold* in a list item.
-#
-#   ===== *Bold* in a Heading
-#
-# Rendered HTML:
-#
-# >>>
-#   *Bold* in a paragraph.
-#
-#   >>>
-#     *Bold* in a block quote.
-#
-#   - *Bold* in a list item.
-#
-#   ===== *Bold* in a Heading
-#
-# ===== Monofont
-#
-# Text may be marked as monofont
-# -- sometimes called 'typewriter font' --
-# via HTML tag <tt><tt></tt> or <tt><code></tt>.
-#
-# Example input:
-#
-#   <tt>Monofont words</tt> in a paragraph.
-#
-#   >>>
-#     <tt>Monofont words</tt> in a block quote.
-#
-#   - <tt>Monofont words</tt> in a list item.
-#
-#   ====== <tt>Monofont words</tt> in heading
-#
-#   <tt>Monofont passage containing _italics_ and *bold*.</tt>
-#
-# Rendered HTML:
-#
-# >>>
-#   <tt>Monofont words</tt> in a paragraph.
-#
-#   >>>
-#     <tt>Monofont words</tt> in a block quote.
-#
-#   - <tt>Monofont words</tt> in a list item.
-#
-#   ====== <tt>Monofont words</tt> in heading
-#
-#   <tt>Monofont passage containing _italics_ and *bold*.</tt>
-#
-# A single word may be made monofont by a shorthand:
-# prefixed and suffixed plus-signs.
-#
-# Example input:
-#
-#   +Monofont+ in a paragraph.
-#
-#   >>>
-#     +Monofont+ in a block quote.
-#
-#   - +Monofont+ in a list item.
-#
-#   ====== +Monofont+ in a Heading
-#
-# Rendered HTML:
-#
-# >>>
-#   +Monofont+ in a paragraph.
-#
-#   >>>
-#     +Monofont+ in a block quote.
-#
-#   - +Monofont+ in a list item.
-#
-#   ====== +Monofont+ in a Heading
-#
-# === Character Conversions
-#
-# Certain combinations of characters may be converted to special characters;
-# whether the conversion occurs depends on whether the special character
-# is available in the current encoding.
-#
-# - <tt>(c)</tt> converts to (c) (copyright character); must be lowercase.
-#
-# - <tt>(r)</tt> converts to (r) (registered trademark character); must be lowercase.
-#
-# - <tt>'foo'</tt> converts to 'foo' (smart single-quotes).
-#
-# - <tt>"foo"</tt> converts to "foo" (smart double-quotes).
-#
-# - <tt>foo ... bar</tt> converts to foo ... bar (1-character ellipsis).
-#
-# - <tt>foo -- bar</tt> converts to foo -- bar (1-character en-dash).
-#
-# - <tt>foo --- bar</tt> converts to foo --- bar (1-character em-dash).
-#
-# === Links
-#
-# Certain strings in \RDoc text are converted to links.
-# Any such link may be suppressed by prefixing a backslash.
-# This section shows how to link to various
-# targets.
-#
-# [Class]
-#
-#   - On-page: <tt>DummyClass</tt> links to DummyClass.
-#   - Off-page: <tt>RDoc::Alias</tt> links to RDoc::Alias.
-#
-#   note: When marking up code (such as class, module,
-#   constant, and method) as "<tt>+code+</tt>" (for interoperability
-#   with other MarkDown parsers mainly), any word that refers to a known
-#   code object, and is marked up entirely and separately as "monofont",
-#   is also converted to a link.
-#
-#   - <tt>+DummyClass+</tt> links to DummyClass
-#   - <tt>+DummyClass-object+</tt> is not a link.
-#
-# [Module]
-#
-#   - On-page: <tt>DummyModule</tt> links to DummyModule.
-#   - Off-page: <tt>RDoc</tt> links to RDoc.
-#
-# [Constant]
-#
-#   - On-page: <tt>DUMMY_CONSTANT</tt> links to DUMMY_CONSTANT.
-#   - Off-page: <tt>RDoc::Text::MARKUP_FORMAT</tt> links to RDoc::Text::MARKUP_FORMAT.
-#
-# [Singleton Method]
-#
-#   - On-page: <tt>::dummy_singleton_method</tt> links to ::dummy_singleton_method.
-#   - Off-page<tt>RDoc::TokenStream::to_html</tt> links to RDoc::TokenStream::to_html.
-#
-#   Note: Occasionally \RDoc is not linked to a method whose name
-#   has only special characters. Check whether the links you were expecting
-#   are actually there.  If not, you'll need to put in an explicit link;
-#   see below.
-#
-#   Pro tip: The link to any method is available in the alphabetical table of contents
-#   at the top left of the page for the class or module.
-#
-# [Instance Method]
-#
-#   - On-page: <tt>#dummy_instance_method</tt> links to #dummy_instance_method.
-#   - Off-page: <tt>RDoc::Alias#html_name</tt> links to RDoc::Alias#html_name.
-#
-#     See the Note and Pro Tip immediately above.
-#
-# [Attribute]
-#
-#   - On-page: <tt>#dummy_attribute</tt> links to #dummy_attribute.
-#   - Off-page: <tt>RDoc::Alias#name</tt> links to RDoc::Alias#name.
-#
-# [Alias]
-#
-#   - On-page: <tt>#dummy_instance_alias</tt> links to #dummy_instance_alias.
-#   - Off-page: <tt>RDoc::Alias#new_name</tt> links to RDoc::Alias#new_name.
-#
-# [Protocol +http+]
-#
-#   - Linked: <tt>http://yahoo.com</tt> links to http://yahoo.com.
-#
-# [Protocol +https+]
-#
-#   - Linked: <tt>https://github.com</tt> links to https://github.com.
-#
-# [Protocol +ftp+]
-#
-#   - Linked: <tt>ftp://nosuch.site</tt> links to ftp://nosuch.site.
-#
-# [Protocol +mailto+]
-#
-#   - Linked:  <tt>mailto:/foo@bar.com</tt> links to mailto://foo@bar.com.
-#
-# [Protocol +irc+]
-#
-#   - link: <tt>irc://irc.freenode.net/ruby</tt> links to irc://irc.freenode.net/ruby.
-#
-# [Image Filename Extensions]
-#
-#   - Link: <tt>https://www.ruby-lang.org/images/header-ruby-logo@2x.png</tt> is
-#     converted to an in-line HTML +img+ tag, which displays the image in the HTML:
-#
-#     https://www.ruby-lang.org/images/header-ruby-logo@2x.png
-#
-#     Also works for +bmp+, +gif+, +jpeg+, and +jpg+ files.
-#
-#     Note: Works only for a fully qualified URL.
-#
-# [Heading]
-#
-#   Headings generate GitHub-style anchors: lowercase, spaces as hyphens,
-#   special characters removed. For example, <tt>== Hello World</tt> generates
-#   anchor <tt>hello-world</tt>.
-#
-#   Link to headings are recommended to use the GitHub-style anchor format:
-#
-#   - <tt>RDoc::Options@saved-options</tt> links to RDoc::Options@saved-options.
-#   - <tt>RDoc::RD@license</tt> links to RDoc::RD@license.
-#
-#   To link to headings on the same page, you can also use Markdown-style anchor links:
-#
-#   - <tt>{link text}[#hello-world]</tt> links to the heading <tt>== Hello World</tt>.
-#   - <tt>{link text}[#saved-options]</tt> links to the heading <tt>== Saved Options</tt>.
-#
-#   The legacy format with <tt>+</tt> for spaces is also supported, but not recommended:
-#
-#   - <tt>RDoc::Options@Saved+Options</tt> links to RDoc::Options@Saved+Options.
-#
-#   Pro tip: The link to any heading is available in the alphabetical table of contents
-#   at the right sidebar of the page.
-#
-# [Section]
-#
-#   See {Directives for Organizing Documentation}[#class-rdoc-markupreference-directives-for-organizing-documentation].
-#
-#   - Link: <tt>RDoc::Markup::ToHtml@Visitor</tt> links to RDoc::Markup::ToHtml@Visitor.
-#
-#   If a section and a heading share the same name, the link target is the section.
-#
-# [Single-Word Text Link]
-#
-#   Use square brackets to create single-word text link:
-#
-#   - <tt>GitHub[https://github.com]</tt> links to GitHub[https://github.com].
-#
-# [Multi-Word Text Link]
-#
-#   Use square brackets and curly braces to create a multi-word text link.
-#
-#   - <tt>{GitHub home page}[https://github.com]</tt> links to
-#     {GitHub home page}[https://github.com].
-#
-# [<tt>rdoc-ref</tt> Scheme]
-#
-#   A link with the <tt>rdoc-ref:</tt> scheme links to the referenced item,
-#   if that item exists.
-#   The referenced item may be a class, module, method, file, etc.
-#
-#   - Class: <tt>Alias[rdoc-ref:RDoc::Alias]</tt> generates Alias[rdoc-ref:RDoc::Alias].
-#   - Module: <tt>RDoc[rdoc-ref:RDoc]</tt> generates RDoc[rdoc-ref:RDoc].
-#   - Method: <tt>foo[rdoc-ref:RDoc::MarkupReference#dummy_instance_method]</tt>
-#     generates foo[rdoc-ref:RDoc::MarkupReference#dummy_instance_method].
-#   - Constant: <tt>bar[rdoc-ref:RDoc::MarkupReference::DUMMY_CONSTANT]</tt>
-#     generates bar[rdoc-ref:RDoc::MarkupReference::DUMMY_CONSTANT].
-#   - Attribute: <tt>baz[rdoc-ref:RDoc::MarkupReference#dummy_attribute]</tt>
-#     generates baz[rdoc-ref:RDoc::MarkupReference#dummy_attribute].
-#   - Alias: <tt>bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias]</tt>
-#     generates bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias].
-#   - File: <tt>README[rdoc-ref:README.md]</tt> generates README[rdoc-ref:README.md].
-#
-#   If the referenced item does not exist, no link is generated
-#   and entire <tt>rdoc-ref:</tt> square-bracketed clause is removed
-#   from the resulting text.
-#
-#   - <tt>Nosuch[rdoc-ref:RDoc::Nosuch]</tt> generates Nosuch.
-#
-#
-# [<tt>rdoc-label</tt> Scheme]
-#
-#   [Simple]
-#
-#     You can specify a link target using this form,
-#     where the second part cites the id of an HTML element.
-#
-#     This link refers to the constant +DUMMY_CONSTANT+ on this page:
-#
-#     - <tt>{DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]</tt>
-#
-#     Thus:
-#
-#     {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]
-#
-#   [With Return]
-#
-#     You can specify both a link target and a local label
-#     that can be used as the target for a return link.
-#     These two links refer to each other:
-#
-#     - <tt>{go to addressee}[rdoc-label:addressee:sender]</tt>
-#     - <tt>{return to sender}[rdoc-label:sender:addressee]</tt>
-#
-#     Thus:
-#
-#     {go to addressee}[rdoc-label:addressee:sender]
-#
-#     Some text.
-#
-#     {return to sender}[rdoc-label:sender:addressee]
-#
-# [<tt>link:</tt> Scheme]
-#
-#   - <tt>link:README_md.html</tt> links to link:README_md.html.
-#
-# [<tt>rdoc-image</tt> Scheme]
-#
-#   Use the <tt>rdoc-image</tt> scheme to display an image that is also a link:
-#
-#     # {rdoc-image:path/to/image}[link_target]
-#
-#   - Link: <tt>{rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]</tt>
-#     displays image <tt>https://www.ruby-lang.org/images/header-ruby-logo@2x.png</tt>
-#     as a link to <tt>https://www.ruby-lang.org</tt>.
-#
-#     {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[https://www.ruby-lang.org]
-#
-#   A relative path as the target also works:
-#
-#   - Link: <tt>{rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html]</tt> links to <tt>./Alias.html</tt>
-#
-#     {rdoc-image:https://www.ruby-lang.org/images/header-ruby-logo@2x.png}[./Alias.html]
-#
-# === Escaping Text
-#
-# Text that would otherwise be interpreted as markup
-# can be "escaped," so that it is not interpreted as markup;
-# the escape character is the backslash (<tt>'\\'</tt>).
-#
-# In a verbatim text block or a code block,
-# the escape character is always preserved:
-#
-# Example input:
-#
-#   This is not verbatim text.
-#
-#     This is verbatim text, with an escape character \.
-#
-#   This is not a code block.
-#
-#     def foo
-#       'String with an escape character.'
-#     end
-#
-# Rendered HTML:
-#
-# >>>
-#   This is not verbatim text.
-#
-#     This is verbatim text, with an escape character \.
-#
-#   This is not a code block.
-#
-#     def foo
-#       'This is a code block with an escape character \.'
-#     end
-#
-# In typeface markup (italic, bold, or monofont),
-# an escape character is preserved unless it is immediately
-# followed by nested typeface markup.
-#
-# Example input:
-#
-#   This list is about escapes; it contains:
-#
-#   - <tt>Monofont text with unescaped nested _italic_</tt>.
-#   - <tt>Monofont text with escaped nested \_italic_</tt>.
-#   - <tt>Monofont text with an escape character \</tt>.
-#
-# Rendered HTML:
-#
-# >>>
-#   This list is about escapes; it contains:
-#
-#   - <tt>Monofont text with unescaped nested _italic_</tt>.
-#   - <tt>Monofont text with escaped nested \_italic_</tt>.
-#   - <tt>Monofont text with an escape character \ </tt>.
-#
-# In other text-bearing blocks
-# (paragraphs, block quotes, list items, headings):
-#
-# - A single escape character immediately followed by markup
-#   escapes the markup.
-# - A single escape character followed by whitespace is preserved.
-# - A single escape character anywhere else is ignored.
-# - A double escape character is rendered as a single backslash.
-#
-#   Example input:
-#
-#     This list is about escapes; it contains:
-#
-#     - An unescaped class name, RDoc, that will become a link.
-#     - An escaped class name, \RDoc, that will not become a link.
-#     - An escape character followed by whitespace \ .
-#     - An escape character \that is ignored.
-#     - A double escape character \\ that is rendered
-#       as a single backslash.
-#
-#   Rendered HTML:
-#
-#   >>>
-#     This list is about escapes; it contains:
-#
-#     - An unescaped class name, RDoc, that will become a link.
-#     - An escaped class name, \RDoc, that will not become a link.
-#     - An escape character followed by whitespace \ .
-#     - An escape character \that is ignored.
-#     - A double escape character \\ that is rendered
-#       as a single backslash.
-#
-# == Derived Documentation
-#
-# [Class]
-#
-#   By default, \RDoc documents:
-#
-#   - \Class name.
-#   - Parent class.
-#   - Included modules.
-#   - Singleton methods.
-#   - Instance methods.
-#   - Aliases.
-#   - Constants.
-#   - Attributes.
-#
-# [Module]
-#
-#   By default, \RDoc documents:
-#
-#   - \Module name.
-#   - Included modules.
-#   - \Singleton methods.
-#   - Instance methods.
-#   - Aliases.
-#   - Constants.
-#   - Attributes.
-#
-# [Method]
-#
-#   By default, \RDoc documents:
-#
-#   - \Method name.
-#   - Arguments.
-#   - Yielded values.
-#
-#   See #method.
-#
-# [Alias]
-#
-#   By default, \RDoc documents:
-#
-#   - Alias name.
-#   - Aliased name.
-#
-#   See #dummy_instance_alias and #dummy_instance_method.
-#
-# [Constant]
-#
-#   By default, \RDoc documents:
-#
-#   - \Constant name.
-#
-#   See DUMMY_CONSTANT.
-#
-# [Attribute]
-#
-#   By default, \RDoc documents:
-#
-#   - Attribute name.
-#   - Attribute type (<tt>[R]</tt>, <tt>[W]</tt>, or <tt>[RW]</tt>)
-#
-#   See #dummy_attribute.
-#
-class RDoc::MarkupReference
-
-  # Example class.
-  class DummyClass; end
-
-  # Example module.
-  module DummyModule; end
-
-  # Example singleton method.
-  def self.dummy_singleton_method(foo, bar); end
-
-  # Example instance method.
-  def dummy_instance_method(foo, bar); end;
-
-  alias dummy_instance_alias dummy_instance_method
-
-  # Example attribute.
-  attr_accessor :dummy_attribute
-
-  alias dummy_attribute_alias dummy_attribute
-
-  # Example constant.
-  DUMMY_CONSTANT = ''
-
-  # :call-seq:
-  #   call_seq_directive(foo, bar)
-  #   Can be anything -> bar
-  #   Also anything more -> baz or bat
-  #
-  # The <tt>:call-seq:</tt> directive overrides the actual calling sequence
-  # found in the Ruby code.
-  #
-  # - It can specify anything at all.
-  # - It can have multiple calling sequences.
-  #
-  # This one includes <tt>Can be anything -> foo</tt>, which is nonsense.
-  #
-  # Note that the "arrow" is two characters, hyphen and right angle-bracket,
-  # which is made into a single character in the HTML.
-  #
-  # Click on the calling sequence to see the code.
-  #
-  # Here is the <tt>:call-seq:</tt> directive given for the method:
-  #
-  #   \:call-seq:
-  #     call_seq_directive(foo, bar)
-  #     Can be anything -> bar
-  #     Also anything more -> baz or bat
-  #
-  def call_seq_directive
-    nil
-  end
-
-  # The <tt>:args:</tt> directive overrides the actual arguments found in the Ruby code.
-  #
-  # Click on the calling sequence to see the code.
-  #
-  def args_directive(foo, bar) # :args: baz
-    nil
-  end
-
-  # The <tt>:yields:</tt> directive overrides the actual yield found in the Ruby code.
-  #
-  # Click on the calling sequence to see the code.
-  #
-  def yields_directive(foo, bar) # :yields: 'bat'
-    yield 'baz'
-  end
-
-  # This method is documented only by \RDoc, except for these comments.
-  #
-  # Click on the calling sequence to see the code.
-  #
-  def method(foo, bar)
-    yield 'baz'
-  end
-
-end
diff --git a/rdoc.gemspec b/rdoc.gemspec
index ada9341fda..494900b245 100644
--- a/rdoc.gemspec
+++ b/rdoc.gemspec
@@ -40,8 +40,8 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
   non_lib_files = [
     "CONTRIBUTING.md",
     "CVE-2013-0256.rdoc",
-    "ExampleMarkdown.md",
-    "ExampleRDoc.rdoc",
+    "doc/markup_reference/markdown.md",
+    "doc/markup_reference/rdoc.rdoc",
     "History.rdoc",
     "LEGAL.rdoc",
     "LICENSE.rdoc",

From f83a68c25cb1abebe840eb1ed031323548c4ed5b Mon Sep 17 00:00:00 2001
From: Stan Lo <stan001212@gmail.com>
Date: Sun, 4 Jan 2026 13:24:26 +0000
Subject: [PATCH 2/2] Tell agent how to properly test reference doc updates

---
 AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 26520d72b6..d44ff39112 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -268,6 +268,53 @@ Use Red, Green, Refactor approach:
 3. Check output in `_site/` directory
 4. Check coverage: `bundle exec rake coverage`
 
+### Modifying Markup Reference Documentation
+
+When editing markup reference documentation, such as `doc/markup_reference/markdown.md` and `doc/markup_reference/rdoc.rdoc`:
+
+1. **Always verify rendering** - After making changes, test that the content renders correctly using Ruby:
+
+   For Markdown files:
+
+   ```ruby
+   ruby -r rdoc -r rdoc/markdown -e '
+   md = RDoc::Markdown.new
+   doc = md.parse("YOUR CONTENT HERE")
+   formatter = RDoc::Markup::ToHtml.new(RDoc::Options.new)
+   puts formatter.convert(doc)
+   '
+   ```
+
+   For RDoc files:
+
+   ```ruby
+   ruby -r rdoc -e '
+   parser = RDoc::Markup::Parser.new
+   doc = parser.parse("YOUR CONTENT HERE")
+   formatter = RDoc::Markup::ToHtml.new(RDoc::Options.new)
+   puts formatter.convert(doc)
+   '
+   ```
+
+2. **Watch for rendering issues:**
+   - Backtick escaping (especially nested code blocks)
+   - Tilde characters being interpreted as strikethrough
+   - Special characters in examples
+   - Anchor links pointing to correct headings
+
+3. **Known RDoc Markdown limitations:**
+   - Only triple backticks for fenced code blocks (no tildes, no quad-backticks)
+   - Tilde fences (`~~~`) conflict with strikethrough syntax
+   - Use 4-space indentation to show literal code fence examples
+
+4. **Full verification**: Generate documentation and inspect the HTML output:
+
+   ```bash
+   bundle exec rake rerdoc
+   # Inspect the generated HTML file directly
+   grep -A5 "your content" _site/path/to/file.html
+   ```
+
 ### Modifying Themes/Styling
 
 When making changes to theme CSS or templates (e.g., Darkfish or Aliki themes):