Implement hybrid rdoc/markdown markup renderer

Author: lsegal

CHANGELOG.md

@@ -1,6 +1,7 @@
 # main
 
 - Add support for Ruby .rbs files (docstrings included)
+- Add built-in hybrid RDoc/Markdown renderer (`HybridMarkdown`) requiring no external gems
 - Add support for `#-` as a comment-block separator. See Getting Started Guide.
 - Fix false self-referential mixin when bare name matches ancestor namespace (#1672)
 - Fix bracket/brace map corruption from Ruby 3.0+ pattern matching deconstruction (#1671)

README.md

@@ -19,10 +19,10 @@ summary of some of YARD's notable features.
 
 ## Feature List
 
-**1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be compatible
-with RDoc formatting. In fact, YARD does no processing on RDoc documentation
-strings, and leaves this up to the output generation tool to decide how to
-render the documentation.
+**1. Builtin RDoc/Markdown Hybrid Support**: YARD ships with a builtin markup
+renderer that supports both RDoc and Markdown formatting out of the box—no
+external gem required. You can freely mix RDoc-style and Markdown-style
+documentation without installing any additional libraries.
 
 **2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other
 languages**: YARD uses a '@tag' style definition syntax for meta tags alongside
@@ -114,20 +114,17 @@ $ gem install yard
 Alternatively, if you've checked the source out directly, you can call
 `rake install` from the root project directory.
 
-**Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby
-install lacks RDoc, which is occasionally used by YARD to convert markup to
-HTML. If running `which rdoc` turns up empty, install RDoc by issuing:
+### Markup rendering
 
-```sh
-$ sudo apt-get install rdoc
-```
-
-### Markdown parser
+YARD includes a builtin renderer that handles both RDoc and Markdown markup
+types without any external dependencies. To switch the default markup type,
+pass `-m markdown` (or `-m rdoc`) to `yard doc`, or add it to your `.yardopts`
+file.
 
-When rendering markdown, yard will use one of several possible markdown providers,
-[in order of priority](https://github.com/lsegal/yard/blob/e833aac7a01510245dd4ae1d1d18b046c8293c2d/lib/yard/templates/helpers/markup_helper.rb#L26-L33).
-If you are experiencing rendering bugs (example [1](https://github.com/lsegal/yard/issues/1410) [2](https://github.com/lsegal/yard/issues/1543)), try adding one of the
-gems further up in the list to your Gemfile.
+For optional extra rendering features (e.g. GitHub-Flavoured Markdown fenced
+code blocks, tables, or specific Markdown extensions), you can install an
+additional provider gem such as `redcarpet`, `commonmarker`, or `kramdown` and
+select it explicitly with `-M PROVIDER` (e.g. `yard doc -m markdown -M redcarpet`).
 
 ## Usage
 

docs/GettingStarted.md

@@ -85,13 +85,17 @@ YARD treats it as a normal comment line and it remains part of the docstring.
 
 ## Which Markup Format?
 
-YARD does not impose a specific markup. The above example uses standard RDoc
-markup formatting, but YARD also supports textile and markdown via the
-command-line switch or `.yardopts` file (see below). This means that you are
-free to use whatever formatting you like. This guide is actually written
-using markdown. YARD, however, does add a few important syntaxes that are
-processed no matter which markup formatting you use, such as tag support
-and inter-document linking. These syntaxes are discussed below.
+YARD does not impose a specific markup format. YARD ships with a builtin
+renderer that supports both RDoc and Markdown out of the box—no external gem
+required. You can use either format (or switch between them) without installing
+anything extra. YARD also supports textile, asciidoc, and other formats via
+optional gems.
+
+To select a markup format, use the command-line switch `-m FORMAT` or add
+`--markup FORMAT` to your `.yardopts` file. This guide is written in Markdown.
+YARD adds a few important syntaxes that are processed regardless of which
+markup format you choose, such as tag support and inter-document linking.
+These syntaxes are discussed below.
 
 ## Adding Tags to Documentation
 

docs/WhatsNew.md

@@ -6,6 +6,24 @@
 
 YARD now supports parsing Ruby signature files (.rbs) with full docstring support. This means you can write your documentation in `.rbs` files and have it show up in generated documentation, and use `.rbs` files alongside `.rb` sources to supplement type and API information.
 
+## New built-in Markdown renderer (0.9.40)
+
+YARD now ships with a built-in Markdown renderer (`YARD::Templates::Helpers::Markup::HybridMarkdown`)
+that requires **no external gems**. It supports a practical subset of GitHub Flavored Markdown (GFM)
+as well as common RDoc markup forms, including:
+
+- ATX and setext headings (`#`, `=`)
+- Fenced code blocks (`` ``` `` and `~~~`) as well as RDoc formatted `+text+` blocks.
+- Tables, blockquotes, and thematic breaks
+- Ordered and unordered lists (including RDoc-style)
+- Inline emphasis, code, links, and images
+- HTML passthrough blocks
+
+This renderer is the **default** for both the `rdoc` and `markdown` markup types—no gem
+installation required. If an optional provider gem (e.g. `redcarpet`, `kramdown`,
+`commonmarker`) is installed and selected, YARD will use it instead for extra features such
+as custom extensions or stricter spec compliance.
+
 ## `#-` comment block separators (0.9.40)
 
 YARD now recognizes a trailing `#-` line as a separator between comment

lib/yard/autoload.rb

@@ -287,6 +287,7 @@ module Tags # Namespace for Tag components
   module Templates
     module Helpers # Namespace for template helpers
       module Markup # Namespace for markup providers
+        autoload :HybridMarkdown,           __p('templates/helpers/markup/hybrid_markdown')
         autoload :RDocMarkup,               __p('templates/helpers/markup/rdoc_markup')
         autoload :RDocMarkdown,             __p('templates/helpers/markup/rdoc_markdown')
       end