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`

Author: st0012

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
 

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

ExampleRDoc.rdoc

@@ -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__)