[DOC] Correction for doc guide + TOC fix in File #8505
Conversation
| - The GFM (GitHub Flavored Markdown) table extension, | ||
| which is enabled by default. See | ||
| {GFM tables extension}[https://github.github.com/gfm/#tables-extension-]. |
There was a problem hiding this comment.
RDoc doe support GFM tables, but only in markdown files. For example, doc/contributing/glossary.md is generated at: https://docs.ruby-lang.org/en/master/contributing/glossary_md.html
There was a problem hiding this comment.
Thanks. Can the doc for a single class/module/method/etc. be markdown? Or must the entire file be markdown? (Asking for a friend.)
There was a problem hiding this comment.
According to the readme:
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.
So I think you can switch to markdown by using :markup: markdown.
| using special formatting for the text: | ||
|
|
||
| - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/doc/contributing/glossary.md?plain=1]. | ||
| - Corresponding {output}[https://docs.ruby-lang.org/en/master/contributing/glossary_md.html]. |
There was a problem hiding this comment.
These examples are well-chosen, and the links to the plain-text source variant is also thoughtful. 👍
There was a problem hiding this comment.
Credit to @peterzhu2118 for the GFM example.
The doc guide is corrected to omit reference to GFM tables, which RDoc does not support.
In linking to verbatim example, I discovered an TOC jump-level that caused most of the headings in File doc to be omitted from the doc's left-TOC for the class. Now corrected.