diff --git a/.github/workflows/cloudflare-preview.yml b/.github/workflows/cloudflare-preview.yml index 2584ad7d30..ffd7281a07 100644 --- a/.github/workflows/cloudflare-preview.yml +++ b/.github/workflows/cloudflare-preview.yml @@ -19,7 +19,7 @@ jobs: ref: ${{ github.event.client_payload.pr_head_sha }} - name: Setup Ruby - uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0 + uses: ruby/setup-ruby@4c24fa5ec04b2e79eb40571b1cee2a0d2b705771 # v1.278.0 with: ruby-version: '3.4' bundler-cache: true diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 2e8ecf196d..2841670659 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -22,7 +22,7 @@ jobs: - name: Checkout uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - name: Setup Ruby - uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0 + uses: ruby/setup-ruby@4c24fa5ec04b2e79eb40571b1cee2a0d2b705771 # v1.278.0 with: ruby-version: '3.2' bundler-cache: true diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index a375f12370..5a6346f86d 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -21,7 +21,7 @@ jobs: - if: ${{ matrix.os == 'ubuntu-latest' }} run: sudo apt install libyaml-dev - name: Set up Ruby - uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0 + uses: ruby/setup-ruby@4c24fa5ec04b2e79eb40571b1cee2a0d2b705771 # v1.278.0 with: ruby-version: 3.3 bundler-cache: true diff --git a/.github/workflows/push_gem.yml b/.github/workflows/push_gem.yml index c1e9f8322c..1da1ebfae4 100644 --- a/.github/workflows/push_gem.yml +++ b/.github/workflows/push_gem.yml @@ -30,7 +30,7 @@ jobs: - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1 - name: Set up Ruby - uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0 + uses: ruby/setup-ruby@4c24fa5ec04b2e79eb40571b1cee2a0d2b705771 # v1.278.0 with: bundler-cache: true ruby-version: ruby diff --git a/.github/workflows/ruby-core.yml b/.github/workflows/ruby-core.yml index d5bb3fb88e..8e5a8ac988 100644 --- a/.github/workflows/ruby-core.yml +++ b/.github/workflows/ruby-core.yml @@ -22,7 +22,7 @@ jobs: timeout-minutes: 30 steps: - name: Set up latest ruby head - uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0 + uses: ruby/setup-ruby@4c24fa5ec04b2e79eb40571b1cee2a0d2b705771 # v1.278.0 with: ruby-version: head bundler: none diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index a44819f1f5..e6eed986e6 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -46,7 +46,7 @@ jobs: - if: ${{ matrix.os == 'ubuntu-latest' }} run: sudo apt install libyaml-dev - name: Set up Ruby - uses: ruby/setup-ruby@ae195bbe749a7cef685ac729197124a48305c1cb # v1.276.0 + uses: ruby/setup-ruby@4c24fa5ec04b2e79eb40571b1cee2a0d2b705771 # v1.278.0 with: ruby-version: ${{ matrix.ruby }} bundler-cache: true # 'bundle install' and cache diff --git a/ExampleMarkdown.md b/ExampleMarkdown.md index fd4359f355..8622fcab77 100644 --- a/ExampleMarkdown.md +++ b/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) - diff --git a/ExampleRDoc.rdoc b/ExampleRDoc.rdoc index b5dd68c19c..750fdc4795 100644 --- a/ExampleRDoc.rdoc +++ b/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 diff --git a/doc/rdoc/markup_reference.rb b/doc/rdoc/markup_reference.rb index 1ceda2656d..1729144f4c 100644 --- a/doc/rdoc/markup_reference.rb +++ b/doc/rdoc/markup_reference.rb @@ -957,22 +957,30 @@ # # [Heading] # -# - Link: RDoc::RD@LICENSE links to RDoc::RDoc::RD@LICENSE. +# Headings generate GitHub-style anchors: lowercase, spaces as hyphens, +# special characters removed. For example, == Hello World generates +# anchor hello-world. # -# Note that spaces in the actual heading are represented by + characters -# in the linkable text. +# Link to headings are recommended to use the GitHub-style anchor format: # -# - Link: RDoc::Options@Saved+Options -# links to RDoc::Options@Saved+Options. +# - RDoc::Options@saved-options links to RDoc::Options@saved-options. +# - RDoc::RD@license 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: +# +# - {link text}[#hello-world] links to the heading == Hello World. +# - {link text}[#saved-options] links to the heading == Saved Options. +# +# The legacy format with + for spaces is also supported, but not recommended: +# +# - RDoc::Options@Saved+Options 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: RDoc::Markup::ToHtml@Visitor links to RDoc::Markup::ToHtml@Visitor. # diff --git a/lib/rdoc/code_object/class_module.rb b/lib/rdoc/code_object/class_module.rb index d7ee36f950..00e406b1a6 100644 --- a/lib/rdoc/code_object/class_module.rb +++ b/lib/rdoc/code_object/class_module.rb @@ -188,10 +188,26 @@ def aref_prefix # :nodoc: end ## - # HTML fragment reference for this module or class. See - # RDoc::NormalClass#aref and RDoc::NormalModule#aref + # HTML fragment reference for this module or class using GitHub-style + # anchor format (lowercase, :: replaced with -). + # + # Examples: + # Foo -> class-foo + # Foo::Bar -> class-foo-bar def aref + "#{aref_prefix}-#{full_name.downcase.gsub('::', '-')}" + end + + ## + # Legacy HTML fragment reference for backward compatibility. + # Returns the old RDoc-style anchor format. + # + # Examples: + # Foo -> class-Foo + # Foo::Bar -> class-Foo::Bar + + def legacy_aref "#{aref_prefix}-#{full_name}" end diff --git a/lib/rdoc/code_object/context/section.rb b/lib/rdoc/code_object/context/section.rb index 16b778174f..7600a16935 100644 --- a/lib/rdoc/code_object/context/section.rb +++ b/lib/rdoc/code_object/context/section.rb @@ -70,11 +70,30 @@ def add_comment(comment) end ## - # Anchor reference for linking to this section + # Anchor reference for linking to this section using GitHub-style format. + # + # Examples: + # "Section" -> "section" + # "One Two" -> "one-two" + # "[untitled]" -> "untitled" def aref title = @title || '[untitled]' + RDoc::Text.to_anchor(title) + end + + ## + # Legacy anchor reference for backward compatibility. + # + # Examples: + # "Section" -> "section" + # "One Two" -> "one+two" + # "[untitled]" -> "5Buntitled-5D" + + def legacy_aref + title = @title || '[untitled]' + CGI.escape(title).gsub('%', '-').sub(/^-/, '') end diff --git a/lib/rdoc/generator/template/aliki/class.rhtml b/lib/rdoc/generator/template/aliki/class.rhtml index 69adfab1ad..5a6fa35b18 100644 --- a/lib/rdoc/generator/template/aliki/class.rhtml +++ b/lib/rdoc/generator/template/aliki/class.rhtml @@ -29,6 +29,7 @@ <% end %> +

<%= klass.type %> <%= klass.full_name %>

@@ -38,6 +39,7 @@ <%- klass.each_section do |section, constants, attributes| %> + <%- klass.each_section do |section, constants, attributes| %> +