Update documentation

Author: st0012

ExampleMarkdown.md

@@ -14,6 +14,18 @@ For the following styles, see ExampleRDoc.rdoc for style examples:
 
 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
@@ -36,4 +48,3 @@ Here is how a blockquote looks.
 > > 75 years?
 
 This text is from [Riker Ipsum](http://rikeripsum.com)
-

ExampleRDoc.rdoc

@@ -3,6 +3,18 @@
 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

doc/rdoc/markup_reference.rb

@@ -957,22 +957,30 @@
 #
 # [Heading]
 #
-#   - Link: <tt>RDoc::RD@LICENSE</tt> links to RDoc::RDoc::RD@LICENSE.
+#   Headings generate GitHub-style anchors: lowercase, spaces as hyphens,
+#   special characters removed. For example, <tt>== Hello World</tt> generates
+#   anchor <tt>hello-world</tt>.
 #
-#   Note that spaces in the actual heading are represented by <tt>+</tt> characters
-#   in the linkable text.
+#   Link to headings are recommended to use the GitHub-style anchor format:
 #
-#   - Link: <tt>RDoc::Options@Saved+Options</tt>
-#     links to RDoc::Options@Saved+Options.
+#   - <tt>RDoc::Options@saved-options</tt> links to RDoc::Options@saved-options.
+#   - <tt>RDoc::RD@license</tt> links to RDoc::RD@license.
 #
-#   Punctuation and other special characters must be escaped like CGI.escape.
+#   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 top left of the page for the class or module.
+#   at the right sidebar of the page.
 #
 # [Section]
 #
-#   See {Directives for Organizing Documentation}[#class-RDoc::MarkupReference-label-Directives+for+Organizing+Documentation].
+#   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.
 #